docs(contributing): add contribution and release guides
This commit is contained in:
Patrick Wozniak
@@ -0,0 +1,7 @@
|
|||||||
|
# Agent Instructions
|
||||||
|
|
||||||
|
- Follow [CONTRIBUTING.md](CONTRIBUTING.md) before changing code, tests, docs, or commit messages.
|
||||||
|
- Use [RELEASE.md](RELEASE.md) for prerelease, npm smoke-test, stable release, tag, and GitHub follow-up work.
|
||||||
|
- Keep changes focused and reviewable; avoid unrelated refactors.
|
||||||
|
- Run the relevant checks before reporting work as done.
|
||||||
|
- Do not commit, tag, push, or publish unless explicitly asked in the current conversation.
|
||||||
+136
@@ -0,0 +1,136 @@
|
|||||||
|
# Contributing
|
||||||
|
|
||||||
|
Thanks for helping improve `pi-commandcode-provider`.
|
||||||
|
|
||||||
|
This is an unofficial Command Code provider for pi. Keep changes small, tested, and easy to review.
|
||||||
|
|
||||||
|
## Development setup
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm install
|
||||||
|
npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
Useful commands:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm run typecheck
|
||||||
|
npm run format:check
|
||||||
|
npm run test:unit
|
||||||
|
npm run test:models
|
||||||
|
npm run test:oauth
|
||||||
|
npm run test:abort
|
||||||
|
npm run test:stream
|
||||||
|
npm run test:pi-local
|
||||||
|
```
|
||||||
|
|
||||||
|
Before opening a PR, run:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm test
|
||||||
|
npm run format:check
|
||||||
|
git diff --check
|
||||||
|
```
|
||||||
|
|
||||||
|
For release and npm smoke-test steps, see [RELEASE.md](RELEASE.md).
|
||||||
|
|
||||||
|
## Pull request guidelines
|
||||||
|
|
||||||
|
- Keep PRs focused on one problem or feature.
|
||||||
|
- Add or update tests for behavior changes.
|
||||||
|
- Update `README.md`, `CHANGELOG.md`, or `RELEASE.md` when user-facing behavior changes.
|
||||||
|
- Avoid broad refactors unless the PR is specifically about refactoring.
|
||||||
|
- Do not include API keys, tokens, real auth files, `.env` files, or other secrets.
|
||||||
|
- Prefer documented/public Command Code API behavior. If compatibility with CLI behavior is needed, document why.
|
||||||
|
- Make sure npm package contents still make sense when `package.json` `files` changes.
|
||||||
|
|
||||||
|
## Testing pi integration changes
|
||||||
|
|
||||||
|
For provider, auth, request-shape, or stream changes, test both local code and the package form when possible.
|
||||||
|
|
||||||
|
Local extension smoke:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
pi --no-extensions -e ./index.ts --list-models commandcode
|
||||||
|
```
|
||||||
|
|
||||||
|
Npm package smoke and isolated `/login` testing are documented in [RELEASE.md](RELEASE.md#test-the-npm-package-in-pi).
|
||||||
|
|
||||||
|
## Commit message rules
|
||||||
|
|
||||||
|
Use Angular-style Conventional Commits.
|
||||||
|
|
||||||
|
Format:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
<type>(<scope>): <subject>
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
feat(auth): support Command Code CLI auth files
|
||||||
|
fix(core): cap max tokens by selected model
|
||||||
|
docs(release): document npm smoke testing
|
||||||
|
test(stream): cover reasoning start events
|
||||||
|
chore(release): publish 0.1.1
|
||||||
|
```
|
||||||
|
|
||||||
|
### Types
|
||||||
|
|
||||||
|
Use one of these types:
|
||||||
|
|
||||||
|
- `feat`: a new user-facing feature
|
||||||
|
- `fix`: a bug fix
|
||||||
|
- `docs`: documentation-only changes
|
||||||
|
- `style`: formatting-only changes, no behavior change
|
||||||
|
- `refactor`: code restructuring without behavior change
|
||||||
|
- `perf`: performance improvement
|
||||||
|
- `test`: adding or changing tests
|
||||||
|
- `build`: package, dependency, or build-system changes
|
||||||
|
- `ci`: CI workflow changes
|
||||||
|
- `chore`: maintenance that does not fit another type
|
||||||
|
- `revert`: revert a previous commit
|
||||||
|
|
||||||
|
### Scopes
|
||||||
|
|
||||||
|
Use a short lowercase scope. Prefer existing project areas:
|
||||||
|
|
||||||
|
- `auth`
|
||||||
|
- `oauth`
|
||||||
|
- `core`
|
||||||
|
- `models`
|
||||||
|
- `stream`
|
||||||
|
- `tests`
|
||||||
|
- `docs`
|
||||||
|
- `release`
|
||||||
|
- `deps`
|
||||||
|
- `ci`
|
||||||
|
|
||||||
|
A scope is strongly recommended. If no scope fits, choose the closest project area instead of omitting it.
|
||||||
|
|
||||||
|
### Subject line
|
||||||
|
|
||||||
|
- Use imperative mood: `fix(auth): read oauth credentials`, not `fixed` or `fixes`.
|
||||||
|
- Keep it concise.
|
||||||
|
- Start lowercase after the colon.
|
||||||
|
- Do not end with a period.
|
||||||
|
|
||||||
|
### Body and footers
|
||||||
|
|
||||||
|
Use a body when the reason is not obvious:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
fix(core): cap max tokens by selected model
|
||||||
|
|
||||||
|
Command Code can return models with lower output limits than the provider-wide cap.
|
||||||
|
Clamp defaults to the selected model so requests do not exceed upstream limits.
|
||||||
|
```
|
||||||
|
|
||||||
|
Breaking changes must be marked with `!` or a `BREAKING CHANGE:` footer:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
feat(api)!: switch to provider api endpoints
|
||||||
|
|
||||||
|
BREAKING CHANGE: removes support for the legacy internal generate endpoint.
|
||||||
|
```
|
||||||
@@ -115,12 +115,13 @@ https://api.commandcode.ai/provider/v1/models
|
|||||||
|
|
||||||
For tests or local mocks, override it with `COMMANDCODE_MODELS_URL`.
|
For tests or local mocks, override it with `COMMANDCODE_MODELS_URL`.
|
||||||
|
|
||||||
## Publish
|
## Contributing
|
||||||
|
|
||||||
```sh
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, PR expectations, and commit message rules.
|
||||||
npm login
|
|
||||||
npm publish --access public
|
## Release
|
||||||
```
|
|
||||||
|
See [RELEASE.md](RELEASE.md) for the prerelease, npm smoke-test, stable publish, git tag, and GitHub follow-up checklist.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|||||||
+192
@@ -0,0 +1,192 @@
|
|||||||
|
# Release Process
|
||||||
|
|
||||||
|
This project uses npm semver releases.
|
||||||
|
|
||||||
|
Recommended flow:
|
||||||
|
|
||||||
|
- publish prereleases with the `next` dist-tag
|
||||||
|
- smoke-test the npm package directly in pi
|
||||||
|
- publish stable releases with the `latest` dist-tag
|
||||||
|
- commit and tag the stable release
|
||||||
|
- comment on the related PR or issue after shipping
|
||||||
|
|
||||||
|
## Prerelease flow
|
||||||
|
|
||||||
|
Use `next` for beta/alpha/manual validation builds.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm version prepatch --preid next --no-git-tag-version
|
||||||
|
npm test
|
||||||
|
npm run format:check
|
||||||
|
npm pack --dry-run
|
||||||
|
npm publish --tag next --access public
|
||||||
|
```
|
||||||
|
|
||||||
|
If npm asks for browser or OTP auth, run the publish command manually and complete the npm prompt.
|
||||||
|
|
||||||
|
Verify the registry state:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm view pi-commandcode-provider@next version dist-tags --json
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
|
||||||
|
- `next` points to the prerelease version
|
||||||
|
- `latest` still points to the previous stable version
|
||||||
|
|
||||||
|
## Test the npm package in pi
|
||||||
|
|
||||||
|
Always test from npm, not the local checkout.
|
||||||
|
|
||||||
|
### 1. Model discovery smoke test
|
||||||
|
|
||||||
|
```sh
|
||||||
|
PI_SKIP_VERSION_CHECK=1 \
|
||||||
|
pi --no-extensions \
|
||||||
|
-e npm:pi-commandcode-provider@next \
|
||||||
|
--list-models commandcode
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
|
||||||
|
- provider `commandcode` appears
|
||||||
|
- live Command Code models are listed
|
||||||
|
|
||||||
|
### 2. Manual `/login` test with isolated pi config
|
||||||
|
|
||||||
|
Use temporary pi config and session directories so the test does not touch your real pi auth.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
export PI_CC_TEST_AGENT_DIR="$(mktemp -d)"
|
||||||
|
export PI_CC_TEST_SESSION_DIR="$(mktemp -d)"
|
||||||
|
|
||||||
|
export PI_CODING_AGENT_DIR="$PI_CC_TEST_AGENT_DIR"
|
||||||
|
export PI_CODING_AGENT_SESSION_DIR="$PI_CC_TEST_SESSION_DIR"
|
||||||
|
export PI_SKIP_VERSION_CHECK=1
|
||||||
|
|
||||||
|
pi --no-extensions \
|
||||||
|
-e npm:pi-commandcode-provider@next \
|
||||||
|
--provider commandcode \
|
||||||
|
--model deepseek/deepseek-v4-flash
|
||||||
|
```
|
||||||
|
|
||||||
|
Inside pi:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
/login
|
||||||
|
```
|
||||||
|
|
||||||
|
Then:
|
||||||
|
|
||||||
|
1. choose **Use a subscription**
|
||||||
|
2. choose **Command Code**
|
||||||
|
3. complete the browser auth flow
|
||||||
|
4. if automatic transfer fails, paste the copied Command Code API key into pi
|
||||||
|
5. send this message:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
Reply exactly: manual-npm-ok
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
|
||||||
|
- login succeeds
|
||||||
|
- a Command Code credential is saved under the temporary `PI_CODING_AGENT_DIR`
|
||||||
|
- the model replies exactly `manual-npm-ok`
|
||||||
|
|
||||||
|
### 3. Post-login print-mode test
|
||||||
|
|
||||||
|
Using the same exported temp variables from above:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
pi --no-extensions \
|
||||||
|
-e npm:pi-commandcode-provider@next \
|
||||||
|
--no-session \
|
||||||
|
-p \
|
||||||
|
--provider commandcode \
|
||||||
|
--model deepseek/deepseek-v4-flash \
|
||||||
|
"Reply exactly: manual-npm-ok"
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
manual-npm-ok
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Cleanup isolated pi config
|
||||||
|
|
||||||
|
Only run this if these variables were created by the test above:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
rm -rf "$PI_CC_TEST_AGENT_DIR" "$PI_CC_TEST_SESSION_DIR"
|
||||||
|
unset PI_CC_TEST_AGENT_DIR PI_CC_TEST_SESSION_DIR
|
||||||
|
unset PI_CODING_AGENT_DIR PI_CODING_AGENT_SESSION_DIR PI_SKIP_VERSION_CHECK
|
||||||
|
```
|
||||||
|
|
||||||
|
## Stable release flow
|
||||||
|
|
||||||
|
After the `next` package is verified, set the intended stable version:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm version 0.1.1 --no-git-tag-version
|
||||||
|
```
|
||||||
|
|
||||||
|
Replace `0.1.1` with the intended stable version.
|
||||||
|
|
||||||
|
Update `CHANGELOG.md`, then run checks:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm test
|
||||||
|
npm run format:check
|
||||||
|
npm pack --dry-run
|
||||||
|
git diff --check
|
||||||
|
```
|
||||||
|
|
||||||
|
Commit and tag:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
git add .
|
||||||
|
git commit -m "Release 0.1.1"
|
||||||
|
git tag -a v0.1.1 -m "Release 0.1.1"
|
||||||
|
```
|
||||||
|
|
||||||
|
Publish stable:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm publish --tag latest --access public
|
||||||
|
```
|
||||||
|
|
||||||
|
If npm asks for browser or OTP auth, run the publish command manually and complete the npm prompt.
|
||||||
|
|
||||||
|
Verify npm:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm view pi-commandcode-provider version dist-tags --json
|
||||||
|
npm view pi-commandcode-provider@0.1.1 version --json
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
|
||||||
|
- `latest` points to the stable version
|
||||||
|
- the stable version exists on npm
|
||||||
|
|
||||||
|
Push commit and tag:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
git push origin main
|
||||||
|
git push origin v0.1.1
|
||||||
|
```
|
||||||
|
|
||||||
|
## GitHub follow-up
|
||||||
|
|
||||||
|
Comment on the related PR and issue after publishing and pushing:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
gh pr comment <number> --body "Shipped in \`pi-commandcode-provider@0.1.1\` / tag \`v0.1.1\`."
|
||||||
|
|
||||||
|
gh issue comment <number> --body "Shipped in \`pi-commandcode-provider@0.1.1\` / tag \`v0.1.1\`."
|
||||||
|
```
|
||||||
|
|
||||||
|
Only comment on PRs or issues actually included in the release.
|
||||||
@@ -23,6 +23,8 @@
|
|||||||
"src/",
|
"src/",
|
||||||
"README.md",
|
"README.md",
|
||||||
"CHANGELOG.md",
|
"CHANGELOG.md",
|
||||||
|
"CONTRIBUTING.md",
|
||||||
|
"RELEASE.md",
|
||||||
"LICENSE"
|
"LICENSE"
|
||||||
],
|
],
|
||||||
"scripts": {
|
"scripts": {
|
||||||
|
|||||||
Reference in New Issue
Block a user