docs: reconcile the two contributing guides - #1126
Merged
Merged
Conversation
docs/contributing.md carried a full second copy of the contribution guide and had not been touched since it was added in #964, while the root CONTRIBUTING.md moved five times. The two disagreed on the product boundary: the docs copy described a sub-package layout with openadapt-ml, openadapt-evals, openadapt-viewer, openadapt-grounding and openadapt-retrieval as the contribution surface, and called this repository "Meta-package, CLI, documentation, CI/CD". It also carried no licensing, open-core or DCO section, so a contributor who landed on it got no sign-off or licensing information at all. Replace it with a short pointer rather than deleting it. docs/index.md states that this directory exists only so old repository links keep resolving, and the GitHub blob URL for this path returns 200. The page is not published to docs.openadapt.ai: this repository's mkdocs nav contains only index.md, docs.yml actively refuses a second publisher for that domain, and https://docs.openadapt.ai/contributing/ returns 404. The canonical site is built from OpenAdaptAI/openadapt-ops. The pointer names what the root guide covers so a reader who arrives here knows whether it answers their question before following the link. Also link CODE_OF_CONDUCT.md from the root guide. The docs copy pointed at the Contributor Covenant and the root guide pointed at nothing, so the project's own code of conduct was unreachable from the guide that contributors are told to read. No CLA reference is added. The root guide states that a CLA is under consideration and not adopted, and links nothing, which is correct today. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
legacy/CONTRIBUTING.md exists and describes the frozen v0.46.0 tree. A reader who followed the pointer and then found it needs to know which one applies to their change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
docs/contributing.mdbecomes a short pointer to the rootCONTRIBUTING.md. The root guide gains a link toCODE_OF_CONDUCT.md.Why
The two guides had drifted.
docs/contributing.mdhas not been touched since #964 added it; rootCONTRIBUTING.mdhas moved five times since. They disagreed on the product boundary:CONTRIBUTING.mddocs/contributing.md(before)openadapt-flowopenadapt-flow,openadapt-agentopenadapt-ml,openadapt-evals,openadapt-viewer,openadapt-grounding,openadapt-retrievaldocs/packages/index.mdalready carries the corrected framing, and calls those five packages "research or historical surfaces". The stale table survived only indocs/contributing.md. So a contributor who landed on the docs copy got a package map the project had already retired and no licensing or sign-off information at all.Why a pointer and not a deletion
Checked before touching anything:
https://docs.openadapt.ai/contributing/returns 404. The page is not published.mkdocs.ymlnav is one entry,index.md, under the site name "Historical OpenAdapt docs notice"..github/workflows/docs.ymlis a guard that refuses a second publisher for the canonical domain. The site is built fromOpenAdaptAI/openadapt-ops.https://github.com/OpenAdaptAI/OpenAdapt/blob/main/docs/contributing.mdreturns 200, anddocs/index.mdsays the directory "is retained only to avoid breaking old repository links".Deleting the file would break the repository links the directory exists to preserve, for no gain. Two full copies drift, and this pair has now proven it. A pointer keeps the URL alive and leaves one copy to maintain.
The pointer says what the root guide covers, so a reader knows whether it answers their question before following the link.
The CLA
No CLA reference is added anywhere in this PR.
The root guide says a CLA "is under consideration but has not been adopted" and links to nothing. That is accurate and it stays as it is.
Separately, and not fixed here:
openadapt-web/CONTRIBUTING.mdlines 23-25 tell contributors "By opening a pull request you agree to the OpenAdapt Contributor License Agreement" and point atopenadapt-flow/CLA.md. That URL returns 404. It is a different repository and CLA work is in flight elsewhere, so this PR leaves it alone rather than propagating the pattern.Code of Conduct
The stale docs page pointed at the Contributor Covenant; the root guide pointed at nothing, so
CODE_OF_CONDUCT.mdwas unreachable from the guide contributors are told to read. One line in the root guide fixes that, so the pointer loses no information the old page carried.Not touched
legacy/CONTRIBUTING.mdis intentionally frozen.legacy/README.mdstates the directory holds "the legacy monolithic OpenAdapt codebase (v0.46.0), which is now frozen", and the file has not changed since #960 moved it there. It describes poetry, flake8 and aMLDSAI/OpenAdaptURL, which is correct for the frozen v0.46.0 tree and wrong for anything current. Leave it.Same shape elsewhere, not fixed here
docs/LEGACY_FREEZE.md(220 lines) anddocs/legacy/freeze.md(230 lines) are the same document twice, and they have already drifted in both directions:docs/legacy/freeze.md.docs/LEGACY_FREEZE.mdnever got that fix and still carries the wrong label.docs/LEGACY_FREEZE.mdhas a "Related Documents" section thatdocs/legacy/freeze.mdlacks, including a link togithub.com/OpenAdaptAI/openadaptmarked "(coming soon)".Both have inbound links, to different paths:
README.mdandlegacy/README.mdpoint atdocs/LEGACY_FREEZE.md;docs/architecture-evolution.mdpoints atdocs/legacy/freeze.md. Picking which path survives is a call for whoever owns the migration guide, so it is not folded into this PR.Checked and clean:
SECURITY.md,CODE_OF_CONDUCT.md,TRADEMARKS.mdandLICENSEare single copies.docs/architecture.mdanddocs/permissions-macos.mdalready open with a canonical pointer to docs.openadapt.ai, which is the convention this PR follows.