66 lines
2.8 KiB
Markdown
66 lines
2.8 KiB
Markdown
# Contributing to portfolio-optimiser-commons
|
|
|
|
Thank you for your interest. Please read this first — the workflow here is deliberately
|
|
narrower than most repositories, and knowing that up front saves you wasted effort.
|
|
|
|
## Code of Conduct
|
|
|
|
Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
|
|
## Pull requests are not accepted
|
|
|
|
The pull-request tab is **switched off** on this forge, across every repository in the
|
|
organisation. That is a published position, not an oversight: this project is solo-maintained,
|
|
and an enabled-but-permanently-empty PR queue would promise a review capacity that does not
|
|
exist.
|
|
|
|
Use **issues** instead. A well-argued issue carries the same information as a patch and costs
|
|
you less to write.
|
|
|
|
## What belongs here, and what does not
|
|
|
|
This repository is the framework-neutral core. Before opening an issue, check which side of the
|
|
boundary your point falls on:
|
|
|
|
| Your point is about | Raise it in |
|
|
|---|---|
|
|
| The normative specs, the example bundles, the golden fixtures | **here** |
|
|
| Behaviour of the MAF implementation | [`portfolio-optimiser`](https://git.fromaitochitta.com/open/portfolio-optimiser) |
|
|
| Behaviour of the Claude Agent SDK implementation | [`portfolio-optimiser-claude`](https://git.fromaitochitta.com/open/portfolio-optimiser-claude) |
|
|
|
|
A change that is true of only one of the two stacks does not belong here, however correct it
|
|
is — that is the whole point of the shared core. See the Non-goals in the [README](README.md).
|
|
|
|
## Reporting an issue
|
|
|
|
Useful issues on a specification repository look different from bug reports on code. The most
|
|
valuable ones name a specific place in the text:
|
|
|
|
- **Quote the section and the sentence**, not just a line number. Line numbers here go stale
|
|
quickly; a section heading plus the wording you are reading survives an edit above it.
|
|
- Say which of the two things you are claiming: that the specification is **internally
|
|
inconsistent**, or that it is **inconsistent with an implementation**. They have different
|
|
remedies, and conflating them is the most common way a report stalls.
|
|
- For a fixture, state the input, the output you expected, and the output you got.
|
|
|
|
## If you are maintaining a consuming repository
|
|
|
|
Sync is **pull-only**, and all edits land here first:
|
|
|
|
```sh
|
|
git subtree pull --prefix=shared commons main --squash
|
|
```
|
|
|
|
**Never run `git subtree push` from a consuming repository.** The reason, and what it cost the
|
|
one time it happened, is documented in the [README](README.md).
|
|
|
|
## Conventions
|
|
|
|
Commits follow [Conventional Commits](https://www.conventionalcommits.org/)
|
|
(`type(scope): description`). Changes to normative text are ratified before they land; the
|
|
reasoning behind each ruling is recorded in [`docs/plan/`](docs/plan/), including for the
|
|
rulings that were later reversed.
|
|
|
|
## Questions?
|
|
|
|
Open an issue.
|