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.

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`
Behaviour of the Claude Agent SDK implementation	`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.

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:

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.

Conventions

Commits follow Conventional Commits (type(scope): description). Changes to normative text are ratified before they land; the reasoning behind each ruling is recorded in docs/plan/, including for the rulings that were later reversed.

Questions?

Open an issue.

2.8 KiB Raw Blame History