138 lines
4.9 KiB
Markdown
138 lines
4.9 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.
|
|
|
|
## 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 procedure](release.md) for version and publication work.
|
|
|
|
## Task-Specific Reading Guide
|
|
|
|
| Task | Read before changing |
|
|
| --- | --- |
|
|
| Documentation or examples | The [documentation policy](policy/documentation.md) and the canonical owner of the affected contract. |
|
|
| Tests or test fixtures | The [testing policy](policy/testing.md), the owning package, and any focused internal document listed by the component overview. |
|
|
| Root public API, once implemented | The [architecture policy](policy/architecture.md), [root package declaration](../doc.go), [testing policy](policy/testing.md), and existing GoDoc. |
|
|
| Internal package implementation, once introduced | The [architecture policy](policy/architecture.md), [internal component overview](internal/overview.md), and any focused internal document that the overview lists for that package. |
|
|
| Integration behavior, once introduced | The [architecture policy](policy/architecture.md), [documentation policy](policy/documentation.md), and the integration's owning contract under `docs/integrations/`. |
|
|
| Release preparation or publication | The [release procedure](release.md). |
|
|
|
|
For cross-cutting changes, follow every applicable row. Do not create
|
|
placeholder documents for packages, APIs, or integrations that do not yet
|
|
exist.
|
|
|
|
## Maintainer-Run Validation
|
|
|
|
Promptkit does not currently use hosted CI. Maintainers are responsible for
|
|
running the documented checks before accepting changes. Run the default Go
|
|
validation from the Promptkit repository root:
|
|
|
|
```sh
|
|
go test ./...
|
|
go vet ./...
|
|
go build ./...
|
|
```
|
|
|
|
Check formatting across every tracked Go file:
|
|
|
|
```sh
|
|
gofmt -l $(git ls-files '*.go')
|
|
```
|
|
|
|
The formatting command must produce no paths. Follow every added or changed
|
|
Markdown link and confirm its target exists. Finally, check whitespace:
|
|
|
|
```sh
|
|
git diff --check
|
|
```
|
|
|
|
Documentation-only work does not require unrelated new tests, but it still
|
|
requires link validation and `git diff --check`. Run the Go validation whenever
|
|
documentation changes commands, examples, generated output, or another
|
|
behavior checked by the module.
|
|
|
|
## Focused Validation
|
|
|
|
Use focused checks while iterating, then run the complete validation sequence
|
|
before accepting the change. The root package currently supports:
|
|
|
|
```sh
|
|
go test .
|
|
go vet .
|
|
go build .
|
|
```
|
|
|
|
Filter tests by name without assuming a future package layout:
|
|
|
|
```sh
|
|
go test ./... -run 'TestName'
|
|
```
|
|
|
|
Replace `TestName` with a useful regular expression. When internal packages are
|
|
introduced, target only paths that actually exist, such as
|
|
`go test ./path/to/package`, and consult the internal component overview for
|
|
their owning documentation. A filtered or package-specific run does not replace
|
|
the complete repository validation.
|
|
|
|
## Coordinated Work With Scriptorium
|
|
|
|
Promptkit and Scriptorium must remain independently valid. For temporary local
|
|
integration, use either a Go workspace outside both repositories or an
|
|
uncommitted replacement in the consuming module.
|
|
|
|
If the repositories are sibling directories, run the workspace commands from
|
|
their parent directory:
|
|
|
|
```sh
|
|
go work init ./promptkit ./scriptorium
|
|
go work sync
|
|
```
|
|
|
|
Use the workspace only for coordinated local checks. From the same parent
|
|
directory, remove it when finished:
|
|
|
|
```sh
|
|
rm -f go.work go.work.sum
|
|
```
|
|
|
|
Alternatively, from the Scriptorium repository root, temporarily point its
|
|
Promptkit dependency at the sibling checkout:
|
|
|
|
```sh
|
|
go mod edit -replace gitea.maximumdirect.net/eric/promptkit=../promptkit
|
|
```
|
|
|
|
After coordinated checks, remove the replacement and reconcile module
|
|
metadata:
|
|
|
|
```sh
|
|
go mod edit -dropreplace gitea.maximumdirect.net/eric/promptkit
|
|
go mod tidy
|
|
```
|
|
|
|
Never commit `go.work`, `go.work.sum`, or a local filesystem `replace`
|
|
directive. Before committing in either repository, inspect its module files and
|
|
working tree independently. Published consumer versions must depend on a tagged
|
|
Promptkit version, not a workspace, local replacement, or unpublished commit.
|