91 lines
5.6 KiB
Markdown
91 lines
5.6 KiB
Markdown
# Development
|
|
|
|
This is the contributor entry point for Promptkit, a reusable Go library. All
|
|
contributors must read the
|
|
[architecture policy](policy/architecture.md) before making changes. Agents must
|
|
also follow the [agent policy](policy/agents.md) before recommendations or work.
|
|
|
|
## 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.
|
|
|
|
Start with:
|
|
|
|
- the [architecture policy](policy/architecture.md) for library boundaries,
|
|
dependency direction, invariants, and non-goals;
|
|
- the [internal component overview](internal/overview.md) for the current
|
|
package and component inventory;
|
|
- the [documentation policy](policy/documentation.md) before changing
|
|
documentation;
|
|
- the [testing policy](policy/testing.md) before adding, rewriting, or deleting
|
|
tests; and
|
|
- the [release policy](policy/release.md) and [release procedure](release.md)
|
|
for version and publication work.
|
|
|
|
## 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. The full
|
|
release-candidate checks have one executable entry point from the repository root:
|
|
|
|
```sh
|
|
./scripts/release-check.sh
|
|
```
|
|
|
|
The [script](../scripts/release-check.sh) owns the executable checks:
|
|
race-enabled tests, vet, the three offline consumer examples with semantic output
|
|
assertions, tracked Go formatting, local Markdown links, module/workspace
|
|
hygiene, whitespace, and the credential-pattern scan. It does not publish,
|
|
change files, validate release-note structure, or retire roadmaps. It requires Go,
|
|
Git, a POSIX shell, and Python 3. Tests and examples require no provider
|
|
credentials or live inference calls.
|
|
|
|
The script can run on intended uncommitted changes during development.
|
|
Formatting and documentation checks use tracked files; stage intended new
|
|
files before final validation so those checks include them. The release
|
|
procedure separately enforces a clean, committed candidate.
|
|
|
|
### 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.
|
|
The automated credential scan does not replace review of the actual change.
|
|
|
|
For releases, follow the [release procedure](release.md). Its publication
|
|
command runs the full local checks once on the final committed candidate and
|
|
automates release-note structure and Git checks. Do not repeat ordinary change
|
|
review as a release 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.
|