104 lines
6.4 KiB
Markdown
104 lines
6.4 KiB
Markdown
# Development
|
|
|
|
This is the contributor entry point for Promptkit, a reusable Go library.
|
|
Use the Policy Reading Guide below to select policies applicable to the task.
|
|
|
|
## Initial Orientation
|
|
|
|
Before starting work:
|
|
|
|
1. inspect the working tree and preserve unrelated changes;
|
|
2. read the policy, contract, and internal documents listed for the task;
|
|
3. inspect the relevant implementation and tests before deciding how to change
|
|
them; and
|
|
4. keep documentation limited to implemented behavior unless an accepted
|
|
decision or temporary roadmap explicitly owns future work.
|
|
|
|
## Policy Reading Guide
|
|
|
|
| Policy | Read before… |
|
|
| --- | --- |
|
|
| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
|
|
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
|
|
| [Architecture](policy/architecture.md) | Planning or changing library code or its structure. |
|
|
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
|
|
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
|
|
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
|
|
| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |
|
|
|
|
- Read applicable policies before making decisions they govern; multiple policies
|
|
may apply.
|
|
- Select policies using the task triggers above. Follow cross-references to
|
|
relevant sections when needed to resolve a concrete question.
|
|
- Reuse policies already available in context; reread when changed or no longer
|
|
available.
|
|
- Expand reading when the task's scope expands.
|
|
- When revising a policy itself, read that policy and any provisions elsewhere
|
|
affected by the revision.
|
|
|
|
## Task-Specific Reading Guide
|
|
|
|
| Task | Read before changing |
|
|
| --- | --- |
|
|
| Root public API | The [architecture policy](policy/architecture.md), [consumer guide](consumers/pkg-promptkit.md), [testing policy](policy/testing.md), and existing GoDoc. |
|
|
| Prompt, profile, or schema formats | The [framework format reference](formats.md), owning parser or validator package, and [documentation policy](policy/documentation.md). |
|
|
| Source loading or validation | The [framework format reference](formats.md), [internal source document](internal/sources.md), and owning package tests. |
|
|
| Maintained external catalogs or built-ins | The [internal source document](internal/sources.md), [framework format reference](formats.md), [testing policy](policy/testing.md), both catalog module repositories, each catalog's release procedure, and the selected module versions in `go.mod`. |
|
|
| Model-client behavior | The [OpenAI-compatible integration contract](integrations/openai-compatible-chat.md), [internal model-client document](internal/llm.md), and owning package tests. |
|
|
| Internal package implementation | The [architecture policy](policy/architecture.md), [internal component overview](internal/overview.md), and focused internal document listed for that package. |
|
|
| Tests or test fixtures | The [testing policy](policy/testing.md), owning package, and focused internal document listed by the component overview. |
|
|
| Maintained example | The [preparation](../examples/go-library/prepare/main.go), [execution](../examples/go-library/run/main.go), and [observation](../examples/go-library/observe/main.go) examples, [consumer guide](consumers/pkg-promptkit.md), [framework format reference](formats.md), and [documentation policy](policy/documentation.md). |
|
|
| Documentation | The [documentation policy](policy/documentation.md) and canonical owner of every affected contract. |
|
|
| Licensing, dependencies/catalog updates, copied material, or attribution | The [OSS policy](policy/oss.md), [project grant](../COPYRIGHT), [license texts](../LICENSE), and [attribution entries](oss/attribution.md); inspect the selected upstream source's notices. |
|
|
| Release preparation or publication, including release notes | The [release policy](policy/release.md), [release procedure](release.md), and [OSS discoverability rules](policy/oss.md#discoverability). |
|
|
|
|
For cross-cutting changes, follow every applicable row. Do not create
|
|
placeholder documents for packages, APIs, or integrations that do not yet
|
|
exist.
|
|
|
|
## Maintainer Validation
|
|
|
|
For ordinary work, select validation proportionate to the change. Do not repeat
|
|
successful checks for unchanged content merely to create a commit. During
|
|
development, run relevant Go tests and vet, format changed Go files, and execute
|
|
the maintained examples when they are affected:
|
|
|
|
```sh
|
|
go test ./...
|
|
go vet ./...
|
|
gofmt -w path/to/changed.go
|
|
python3 scripts/check-examples.py
|
|
git diff --check
|
|
```
|
|
|
|
Release candidates use `./scripts/release.sh VERSION`, which runs the selected
|
|
profile checks and publishes the tag. The [release procedure](release.md)
|
|
describes its requirements and recovery. For an optional diagnostic of a
|
|
committed candidate without publication, run `./scripts/releasekit.sh check
|
|
VERSION`; this is not a required pre-publication step.
|
|
|
|
The standalone `python3 scripts/check-examples.py` command checks semantic
|
|
expectations for the three offline consumer examples. The focused
|
|
`python3 scripts/test-release.py` command exercises the release tooling against
|
|
disposable local repositories; use it when changing that tooling, not as a
|
|
recurring release gate. Tests and examples require no provider credentials or
|
|
live inference calls.
|
|
|
|
Ordinary validation can run on intended uncommitted work. Release validation
|
|
uses committed candidate contents and the selected local Go installation.
|
|
|
|
### Change Review
|
|
|
|
Inspect `git status --short --untracked-files=all` and the complete diff before
|
|
accepting a change. Reject unintended files, credentials, private data,
|
|
generated binaries, test output, downloaded assets, and template residue.
|
|
|
|
For releases, follow the [release procedure](release.md). Do not repeat its
|
|
candidate checks as a separate sign-off. Roadmap retirement remains preparation
|
|
housekeeping.
|
|
|
|
Follow the [agent commit policy](policy/agents.md#git-commit-policy) for local
|
|
commits. Ordinary commits may leave unrelated work in the workspace; preserve
|
|
and report it. A clean worktree and index are required for release candidates,
|
|
as enforced by the publication command, not for every ordinary commit.
|