From 6432a5d5c02a822027224714cf3157f1ddcea225 Mon Sep 17 00:00:00 2001 From: abrichr Date: Fri, 28 Aug 2026 00:01:29 -0400 Subject: [PATCH 1/2] docs: make docs/contributing.md a pointer to the root guide 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 --- CONTRIBUTING.md | 3 + docs/contributing.md | 142 +++---------------------------------------- 2 files changed, 12 insertions(+), 133 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a2bbedc8b..847fe7de7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,9 @@ Thank you for your interest in contributing to OpenAdapt! +Participation in this project is governed by the +[Code of Conduct](CODE_OF_CONDUCT.md). + ## Product boundary `OpenAdaptAI/OpenAdapt` is the launcher/meta-package and compatibility diff --git a/docs/contributing.md b/docs/contributing.md index 651b18e61..46e3e94fa 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,135 +1,11 @@ # Contributing to OpenAdapt -Thank you for your interest in contributing to OpenAdapt! - -## Architecture - -OpenAdapt uses a modular meta-package architecture. The main `openadapt` package coordinates these sub-packages: - -| Package | Purpose | Repository | -|---------|---------|------------| -| openadapt-capture | GUI recording | [openadapt-capture](https://github.com/OpenAdaptAI/openadapt-capture) | -| openadapt-ml | ML training/inference | [openadapt-ml](https://github.com/OpenAdaptAI/openadapt-ml) | -| openadapt-evals | Benchmark evaluation | [openadapt-evals](https://github.com/OpenAdaptAI/openadapt-evals) | -| openadapt-viewer | HTML visualization | [openadapt-viewer](https://github.com/OpenAdaptAI/openadapt-viewer) | -| openadapt-grounding | UI element localization | [openadapt-grounding](https://github.com/OpenAdaptAI/openadapt-grounding) | -| openadapt-retrieval | Multimodal retrieval | [openadapt-retrieval](https://github.com/OpenAdaptAI/openadapt-retrieval) | -| openadapt-privacy | PII/PHI scrubbing | [openadapt-privacy](https://github.com/OpenAdaptAI/openadapt-privacy) | - -## Where to Contribute - -- **This repository**: Meta-package, CLI, documentation, CI/CD -- **Sub-packages**: Open issues in the relevant repository above - -## Getting Started - -### 1. Fork the Repository - -Click the "Fork" button on GitHub for the repository you want to contribute to. - -### 2. Clone Your Fork - -```bash -git clone https://github.com/YOUR-USERNAME/OpenAdapt -# or for a sub-package: -git clone https://github.com/YOUR-USERNAME/openadapt-ml -``` - -### 3. Create a Branch - -```bash -cd OpenAdapt -git checkout -b feature/my-change -``` - -### 4. Install in Development Mode - -```bash -pip install -e ".[dev]" -``` - -### 5. Make Your Changes - -Edit the code, add tests, update documentation. - -### 6. Run Tests - -```bash -pytest -``` - -### 7. Submit a Pull Request - -```bash -git add . -git commit -m "Description of change" -git push origin feature/my-change -``` - -Then open a pull request on GitHub. - -## Development Setup - -### Main Package - -```bash -git clone https://github.com/OpenAdaptAI/OpenAdapt -cd OpenAdapt -pip install -e ".[dev]" -``` - -### Sub-packages - -```bash -git clone https://github.com/OpenAdaptAI/openadapt-ml -cd openadapt-ml -pip install -e ".[dev]" -``` - -## Guidelines - -### Code Style - -- Follow existing code style -- Use type hints for function signatures -- Format with `ruff format` or `black` -- Lint with `ruff check` or `flake8` - -### Testing - -- Add tests for new functionality -- Ensure existing tests pass -- Use pytest for test framework - -### Documentation - -- Update docstrings for API changes -- Update README for feature changes -- Add examples where helpful - -### Pull Requests - -- Keep PRs focused and small -- Write clear descriptions -- Reference related issues -- Respond to review feedback - -## Code of Conduct - -Be respectful and inclusive. We follow the [Contributor Covenant](https://www.contributor-covenant.org/). - -## Questions? - -- [Discord](https://discord.gg/yF527cQbDG) - Real-time chat -- [GitHub Discussions](https://github.com/OpenAdaptAI/OpenAdapt/discussions) - Longer discussions -- [GitHub Issues](https://github.com/OpenAdaptAI/OpenAdapt/issues) - Bug reports and features - -## Recognition - -Contributors are recognized in: - -- GitHub contributor graphs -- Release notes -- Project documentation - -Thank you for helping make OpenAdapt better! +The contribution guide for this repository is +[CONTRIBUTING.md](https://github.com/OpenAdaptAI/OpenAdapt/blob/main/CONTRIBUTING.md) +in the repository root, and that is the only copy. + +Read it there for the product boundary between this launcher and the +[openadapt-flow](https://github.com/OpenAdaptAI/openadapt-flow) engine, the +development install and the checks a pull request has to pass, the open-core +licensing rules that apply to a public repository, and the Developer +Certificate of Origin that covers every contribution. From 0c3e71eb959bd31560c356a38108a62b7363cdb4 Mon Sep 17 00:00:00 2001 From: abrichr Date: Fri, 28 Aug 2026 00:04:51 -0400 Subject: [PATCH 2/2] docs: name the frozen legacy guide so 'maintained copy' is exact 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 --- docs/contributing.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index 46e3e94fa..a7d222526 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -2,7 +2,8 @@ The contribution guide for this repository is [CONTRIBUTING.md](https://github.com/OpenAdaptAI/OpenAdapt/blob/main/CONTRIBUTING.md) -in the repository root, and that is the only copy. +in the repository root. That is the maintained copy. The guide under +`legacy/` applies to the frozen v0.46.0 tree and not to current work. Read it there for the product boundary between this launcher and the [openadapt-flow](https://github.com/OpenAdaptAI/openadapt-flow) engine, the