Contributing¶
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
Please read the Birdhouse Developer Documentation to get started.
Policy¶
Since Birdhouse is used in production by multiple organizations, this deployment repository also has a policy regarding contributions.
Policy objectives¶
Keep production stable between deployments
Encourage PR to be merged more quickly
- Achieve the two previous objectives
by weighing down everyone’s workflow as little as possible
by having an approach that scales well as more nodes go into production and the number of PR increases
Policy rules¶
The repository has a main branch, “master”, open to the community where contributions, “PR”, are welcome. This master branch must not have owners and therefore no organization can block contributions to it.
Contributions should be backward-compatible whenever possible, or feature a toggle switch so that organizations can activate the new feature on their own schedule. See extra core components and optional components for examples.
Contributions will trigger a test suite that must successfully pass before being merged (or integrated).
The test suite can be run using a different DACCS config with
birdhouse_daccs_configs_branch: {branch_name}
in the PR description.To globally skip the test suite regardless of the commit message use
birdhouse_skip_ci: true
in the PR description.It is possible to skip the test suite if the latest commit message contains
[skip ci]
.
Contributions must be reviewed by every willing organizations (Default reviewers are @mishaschwartz for UofT , @tlvu for Ouranos and @fmigneault for CRIM).
The reviews must be rigorous while respecting the initial scope.
Each organization wishing to review the changes has the duty to do so within a reasonable period of time (7 days) or to indicate its intention to do so later with reasonable reasons (e.g., vacation). After this time, its implicit support will be considered. It will be assumed that the organization agrees to the changes, and they will get merged without further notice.
To encourage review in a timely manner, contributions should be simple and focused (do not mix multiple goals) and well explained (describe the “why” and the “impact/behavior change” on existing production deployment, as requested in the contribution template). They should also include a description of provided modifications and fixes under the active
Unreleased
section of the CHANGES.md history file for traceability.
Each organization maintains a fork for its production allowing it to deploy the platform at its own pace. It also allows to self-manage the production fork contribution permissions and develop feature branches.
Each organization is responsible for keeping its production fork up to date with the main branch to avoid discrepancies.
If patches or contributions are made directly in the production fork, they must also be ported back and approved in the main branch (no code that does not exist in the main branch should exist in a production fork).
The main branch will contain the official versions of Birdhouse that will evolve according to semantic versioning. These versions should be used by the organizations.
If contributions are made directly in a production fork (point 10), a tagged version should use the last common one with the main branch but also include a suffix.
Example: The main branch is at
2.1.8
, and a contribution is made in a production fork from2.1.8
. The tag2.1.9
cannot be applied because this version could possibly exists in the main branch. A tag looking like2.1.8.orgXrev1
would be preferred.