From 51b8a7bff197892d2cfa5124c59a56f937ab6955 Mon Sep 17 00:00:00 2001 From: Sanjeev Lakhwani Date: Tue, 19 May 2026 10:58:39 -0400 Subject: [PATCH 1/7] docs: add CONTRIBUTING.md --- CONTRIBUTING.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..47fe06097 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,116 @@ +# Contributing to Bento + +Thanks for your interest in contributing to **Bento**, a genomics data orchestration service developed by the [Canadian Centre for Computational Genomics](https://computationalgenomics.ca/). + +Bento is a collection of microservices distributed across multiple sub-repositories. Most contribution workflows are similar across repos, but some details (setup, tests, linting) live in each sub-repo's own `README`. This document covers the conventions that apply platform-wide. + +## Code of Conduct + +This project and everyone participating in it is expected to abide by a code of conduct. We follow the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By participating, you agree to uphold its terms. Report unacceptable behavior to the maintainers. + +## Getting Started + +### Setup + +Setup instructions live in each repository's `README.md`. Start there for environment configuration, dependencies, and how to run the service locally. + +For the main Bento distribution, see the [development docs](https://github.com/bento-platform/bento/blob/main/docs/development.md). + +### Running tests and linters + +Each sub-repository defines its own testing and linting setup. Check the relevant `README.md` and the GitHub Actions workflows in `.github/workflows/` to see exactly which commands are run in CI — your local checks should match those. + +## Finding Something to Work On + +Internal contributors track work in **Redmine**. Before starting on something: + +1. Find or create a ticket in Redmine that describes the work. +2. Assign the ticket to yourself. +3. Keep the status up to date (e.g., *In Progress*, *In Review*, *Closed*) as you progress. + +This keeps the team aware of who is working on what and avoids duplicated effort. + +## Making Changes + +### Branch naming + +Use descriptive, prefixed branch names. Recommended conventions: + +- `feature/` — new functionality +- `fix/` — bug fixes +- `chore/` — tooling, refactors, dependency bumps +- `docs/` — documentation-only changes + +Including the Redmine ticket ID is encouraged, e.g. `feature/1234-add-search-endpoint`. + +### Commits + +We follow [Conventional Commits](https://www.conventionalcommits.org/). Each commit message should look like: + +``` +(): + + + + +``` + +Common types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `build`, `ci`, `perf`. + +Examples: + +``` +feat(katsu): add phenopacket v2 ingest endpoint +fix(gohan): handle empty VCF gracefully +docs: clarify bentoctl installation steps +``` + +### Code style + +Each sub-repository specifies its own formatter and linter. Use the tool configured in that repo, and check the repo's GitHub Actions lint workflow to ensure your changes pass the same checks CI will run. If a pre-commit hook or formatter config (e.g., `pyproject.toml`, `.eslintrc`, `.prettierrc`) is present, use it. + +## Pull Requests + +### Opening a PR + +- Open the PR against the appropriate base branch (usually `main` unless otherwise noted). +- Use a clear, conventional-commit-style title (e.g., `feat(service): add X`). +- In the description, include: + - A short summary of the change and why it's needed. + - A link to the relevant Redmine ticket. + - Notes on anything reviewers should pay extra attention to (migrations, breaking changes, config updates). + - Testing notes — what you ran and what you observed. +- Keep PRs focused. Smaller, single-purpose PRs are easier to review and merge. + +### Reviews + +Pick reviewers based on context: + +- Anyone who has recently worked on or owns the affected area of the codebase. +- Anyone else whose input you think is relevant (domain knowledge, dependent service owners, etc.). + +At least one approval is required before merging. For larger or cross-cutting changes, get an additional reviewer. + +### CI and merging + +- All CI checks (tests, linters, builds) **must pass** before a PR can be merged. +- Address review comments before re-requesting review. +- **Squash and merge** is the default merge strategy, so that the main branch keeps a clean, conventional-commits history. Use a regular merge commit only when individual commits are meaningful and should be preserved. + +## Reporting Bugs and Security Issues + +To report a bug or security issue, please use this form: + +👉 [Bug/security report form](https://forms.gle/gtihcUDUpa64b14R6) + +For security issues, please **do not** open a public GitHub issue. The form is the right channel — it lets us triage and respond privately before any disclosure. + +## Licensing of Contributions + +Bento is licensed under the [GNU Lesser General Public License v3.0 (LGPL-3.0)](./LICENSE). By submitting a contribution, you agree that your contribution will be licensed under the same LGPL-3.0 terms. + +If you are contributing on behalf of an organization, make sure you have the authority to do so. + +--- + +Thanks for helping make Bento better! 🎉 \ No newline at end of file From e57023f1bedbbdc4d9337a87170cc49f15a79e9e Mon Sep 17 00:00:00 2001 From: Sanjeev Lakhwani Date: Thu, 21 May 2026 11:52:28 -0400 Subject: [PATCH 2/7] =?UTF-8?q?docs:=20fix=20merge=20strategy=20=E2=80=94?= =?UTF-8?q?=20use=20merge=20commit=20not=20squash?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47fe06097..0cd7a16f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,7 +95,7 @@ At least one approval is required before merging. For larger or cross-cutting ch - All CI checks (tests, linters, builds) **must pass** before a PR can be merged. - Address review comments before re-requesting review. -- **Squash and merge** is the default merge strategy, so that the main branch keeps a clean, conventional-commits history. Use a regular merge commit only when individual commits are meaningful and should be preserved. +- **Merge commit** is the default merge strategy. Individual commits are preserved in the history. ## Reporting Bugs and Security Issues From c1083afc63cb2fc0dcad3a9e621ed5ae82a07476 Mon Sep 17 00:00:00 2001 From: Sanjeev Lakhwani Date: Thu, 21 May 2026 11:55:44 -0400 Subject: [PATCH 3/7] docs: use generic scope placeholder in PR title example --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0cd7a16f9..eaf77f725 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,7 +74,7 @@ Each sub-repository specifies its own formatter and linter. Use the tool configu ### Opening a PR - Open the PR against the appropriate base branch (usually `main` unless otherwise noted). -- Use a clear, conventional-commit-style title (e.g., `feat(service): add X`). +- Use a clear, conventional-commit-style title (e.g., `feat(): add X` or `fix: handle Y`). - In the description, include: - A short summary of the change and why it's needed. - A link to the relevant Redmine ticket. From fdf812b5c74ff209f9f6f4beff60bbdbe8f11440 Mon Sep 17 00:00:00 2001 From: Sanjeev Lakhwani Date: Mon, 1 Jun 2026 09:05:59 -0400 Subject: [PATCH 4/7] docs: address PR review comments on CONTRIBUTING.md --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eaf77f725..1b696ae84 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ Internal contributors track work in **Redmine**. Before starting on something: 1. Find or create a ticket in Redmine that describes the work. 2. Assign the ticket to yourself. -3. Keep the status up to date (e.g., *In Progress*, *In Review*, *Closed*) as you progress. +3. Keep the status and `% completed` up to date (e.g., *In Progress*, *In Review*, *Closed*) as you progress. This keeps the team aware of who is working on what and avoids duplicated effort. @@ -38,7 +38,8 @@ Use descriptive, prefixed branch names. Recommended conventions: - `feature/` — new functionality - `fix/` — bug fixes -- `chore/` — tooling, refactors, dependency bumps +- `refactor/` — refactors +- `chore/` — tooling, dependency bumps - `docs/` — documentation-only changes Including the Redmine ticket ID is encouraged, e.g. `feature/1234-add-search-endpoint`. From 45542d04e5d784b531fd48b9e8e729889b29bed3 Mon Sep 17 00:00:00 2001 From: Sanjeev Lakhwani Date: Mon, 1 Jun 2026 13:42:21 -0400 Subject: [PATCH 5/7] docs: address PR review comments on CONTRIBUTING.md --- CONTRIBUTING.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b696ae84..281e97a18 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,11 +10,11 @@ This project and everyone participating in it is expected to abide by a code of ## Getting Started -### Setup +### Development environment -Setup instructions live in each repository's `README.md`. Start there for environment configuration, dependencies, and how to run the service locally. +To work on Bento or any of its services, start by installing Bento itself — you do not need to clone individual service repositories first. Follow the instructions in this repository's [README](./README.md). -For the main Bento distribution, see the [development docs](https://github.com/bento-platform/bento/blob/main/docs/development.md). +If you want to work on a specific service, see the [development guide](https://github.com/bento-platform/bento/blob/main/docs/development.md). Then refer to that service repository's `README.md` for further instructions. ### Running tests and linters @@ -74,7 +74,7 @@ Each sub-repository specifies its own formatter and linter. Use the tool configu ### Opening a PR -- Open the PR against the appropriate base branch (usually `main` unless otherwise noted). +- Open the PR against the appropriate base branch (usually `main`). In the main `bento` repository, active development targets the current release branch (e.g., `releases/v24`) — check with your team if unsure. - Use a clear, conventional-commit-style title (e.g., `feat(): add X` or `fix: handle Y`). - In the description, include: - A short summary of the change and why it's needed. @@ -92,15 +92,21 @@ Pick reviewers based on context: At least one approval is required before merging. For larger or cross-cutting changes, get an additional reviewer. +**As a reviewer:** + +- Aim to review within 1–2 business days of being assigned. +- Distinguish blocking from non-blocking comments. Prefix non-blocking suggestions with `nit:` or `optional:` so the author knows they can merge without resolving them. +- Use "Request changes" for issues that must be fixed before merging. Use "Comment" for questions or non-blocking feedback. Use "Approve" when you're satisfied the PR is ready. + ### CI and merging - All CI checks (tests, linters, builds) **must pass** before a PR can be merged. - Address review comments before re-requesting review. - **Merge commit** is the default merge strategy. Individual commits are preserved in the history. -## Reporting Bugs and Security Issues +## Reporting Bugs, Requesting Changes, and Security Issues -To report a bug or security issue, please use this form: +To report a bug, request a change, or report a security issue, please use this form: 👉 [Bug/security report form](https://forms.gle/gtihcUDUpa64b14R6) From 8f98f782a90844648e5f275d13cefc248cd37a45 Mon Sep 17 00:00:00 2001 From: Sanjeev Lakhwani Date: Wed, 3 Jun 2026 11:24:31 -0400 Subject: [PATCH 6/7] docs: clarify commit scope conventions with bento vs sub-service examples --- CONTRIBUTING.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 281e97a18..8425e00bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,7 +58,7 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/). Each com Common types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `build`, `ci`, `perf`. -Examples: +Examples — committing in the main `bento` repository, where the scope is the affected service: ``` feat(katsu): add phenopacket v2 ingest endpoint @@ -66,6 +66,13 @@ fix(gohan): handle empty VCF gracefully docs: clarify bentoctl installation steps ``` +Examples — committing inside a sub-service repository (e.g. `katsu`), where the scope is the affected internal module or app: + +``` +feat(phenopacket): add compound key of individual id and dataset id to support multiple phenopacket imports +test(chord): add tests for dataset ingestion +``` + ### Code style Each sub-repository specifies its own formatter and linter. Use the tool configured in that repo, and check the repo's GitHub Actions lint workflow to ensure your changes pass the same checks CI will run. If a pre-commit hook or formatter config (e.g., `pyproject.toml`, `.eslintrc`, `.prettierrc`) is present, use it. From 59722f81a2b60f3eef55c03dfe2c1083b5490a38 Mon Sep 17 00:00:00 2001 From: Sanjeev Lakhwani <52885662+SanjeevLakhwani@users.noreply.github.com> Date: Wed, 22 Jul 2026 11:10:00 -0400 Subject: [PATCH 7/7] Fix punctuation and capitalization in CONTRIBUTING.md Corrected punctuation and capitalization for clarity. --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8425e00bc..961d477c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,13 +12,13 @@ This project and everyone participating in it is expected to abide by a code of ### Development environment -To work on Bento or any of its services, start by installing Bento itself — you do not need to clone individual service repositories first. Follow the instructions in this repository's [README](./README.md). +To work on Bento or any of its services, start by installing Bento itself; You do not need to clone individual service repositories first. Follow the instructions in this repository's [README](./README.md). If you want to work on a specific service, see the [development guide](https://github.com/bento-platform/bento/blob/main/docs/development.md). Then refer to that service repository's `README.md` for further instructions. ### Running tests and linters -Each sub-repository defines its own testing and linting setup. Check the relevant `README.md` and the GitHub Actions workflows in `.github/workflows/` to see exactly which commands are run in CI — your local checks should match those. +Each sub-repository defines its own testing and linting setup. Check the relevant `README.md` and the GitHub Actions workflows in `.github/workflows/` to see exactly which commands are run in CI, your local checks should match those. ## Finding Something to Work On @@ -127,4 +127,4 @@ If you are contributing on behalf of an organization, make sure you have the aut --- -Thanks for helping make Bento better! 🎉 \ No newline at end of file +Thanks for helping make Bento better! 🎉