-
Notifications
You must be signed in to change notification settings - Fork 0
docs: add CONTRIBUTING.md and rewrite AGENTS.md #3
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
054dc0d
docs: add AGENTS.md with agent guidelines for the package
Ethan-Arrowood 762ae14
docs: add CONTRIBUTING.md and rewrite AGENTS.md
Ethan-Arrowood e962c1f
okay fine ill do it myself
Ethan-Arrowood 49416cb
edits
Ethan-Arrowood b204905
more edits
Ethan-Arrowood File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # AGENTS.md | ||
|
|
||
| Review the `README.md` and `CONTRIBUTING.md` for all relevant repository information. | ||
|
|
||
| ## Development Tips | ||
| - Ensure you're on at least Node.js v22 or greater when contributing | ||
| - Use `npm install` to install dependencies | ||
| - Use `npm run build` to build the project | ||
| - Do not run `npm version` or `npm publish`; these commands are for humans only. | ||
| - When updating core code, make sure to update relevant documentation. | ||
| - Public API and usage docs are in `README.md` | ||
| - Internal documentation is in `CONTRIBUTING.md` | ||
| - If you change the public API surface in `src/index.ts`, update `README.md#api`. | ||
| - Do not edit files in `dist/`; it is compiled output and gitignored. | ||
|
|
||
| ## Code Style | ||
| - Use ESM and TypeScript | ||
| - Use erasable syntax only (no `enum` or `namespace`) | ||
| - There is currently no linter or formatter for this project | ||
|
|
||
| ## Testing Tips | ||
| - Use `npm link` in this directory and `npm link @harperfast/integration-testing` in other project directories to test out changes locally | ||
| - Use `npm run check` to type-check the project without generating a build output | ||
| - There are currently no tests for this project | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # Contributing | ||
|
|
||
| Contributors are encouraged to communicate with maintainers in issues or other channels (such as our community [Discord](https://harper.fast/discord)) before submitting changes. | ||
|
|
||
| ## Code Organization | ||
|
|
||
| Source files are located in `src/`. These are built to the `dist/` directory. The published package includes `dist/`, `scripts/`, and the regular npm metadata and documentation files. | ||
|
|
||
| The `src/index.ts` is the source for the main export. This is the public re-export of all the various utilities from `src/harperLifecycle.ts`, `targz.ts`, and more. The `src/run.ts` is the source for the `harper-integration-test-run` bin script. And the `scripts/setup-loopback.sh` is the source for the `harper-integration-test-setup-loopback` bin script. | ||
|
|
||
| The package is `"type": "module"` — all source files are ESM by default. | ||
|
|
||
| There are two `tsconfig` files: | ||
|
|
||
| - `tsconfig.json` — type-checking only (`"noEmit": true`). Used by `npm run check` and editors. | ||
| - `tsconfig.build.json` — emits to `dist/` with source maps and declarations. Used by `npm run build`. | ||
|
|
||
| `erasableSyntaxOnly: true` is set, meaning TypeScript-only syntax that cannot be stripped (e.g., `enum`, `namespace`) is not allowed. | ||
|
|
||
| ## Scripts | ||
|
|
||
| ```sh | ||
| npm run check # Type-check only (no output) | ||
| npm run build # Compile src/ → dist/ | ||
| ``` | ||
|
|
||
| There are no automated tests in this package yet. Validation is type-checking plus manual testing via dependent projects. | ||
|
|
||
| ## Releases | ||
|
|
||
| Update the `version` field in `package.json` (recommend using `npm version <major|minor|patch>`) and publish via `npm publish`. The `files` field in `package.json` controls what is included in the published package. Don't forget to push the version commit and tag. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm curious, have you seen examples of AI not picking up on the code style? Or noticing the erasableSyntaxOnly in the tsconfig.json?
I have been thinking that the main value of AGENTS.md:
But definitely curious where we find other values.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I generally agree with that. Here is the definition I've come up with for AGENTS.md:
We can reasonably assume an agent can read the tsconfig and discern facts from it, but that then requires it reading the tsconfig and interpreting those rules every new session. By putting the important stuff in the AGENTS.md, it can skip reading tsconfig unless it has to (to say debug a TS issue).
I think its very arbitrary what we do or don't include in an agents.md file. The important bits is that it should be factual and succinct. I think if we find the agent constantly looking for additional information about the project when its tasked with doing something, we may want to add that information to the agents.md document.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Btw I incorporated some of your thinking in some general guidelines for this doc: HarperFast/code-guidelines#9 want to iterate on it there?