98 lines
6.3 KiB
Markdown
98 lines
6.3 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. 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.
|