-
Notifications
You must be signed in to change notification settings - Fork 214
Maintainence Guidelines
This page documents some principles of the atsamd-rs maintainers, it contains some guidelines but is not a guide. Maintaining an open-source project is both a technical and social pursuit, with plenty room for subjectivity and personality.
For contributors, this page is meant to share how we handle maintenance of the atsamd-rs project. For maintainers, this page is meant to help guide choices that need to be made during maintenance, and provide a level of consistency across the project.
This project is entirely voluntary; although some of us are professionals who use the project for commercial purposes, we are not obligated to work on this project, nor to do that work in any particular way.
Clear communication is important both in discussion threads, and in the documentation and examples we provide, so that contributors and users can understand how to interact with our project. A technically great API isn't of much use if it's hard to discover or to understand.
The atsamd-rs project is used in a wide variety of contexts from curious hobbyists tinkering with embedded programming for the first time, to experienced developers developing mass-manufactured products. We aim for a quality of code and documentation that supports all these usages. This might mean supporting a smaller amount of functionality well, vs less robust support for more functionality.
To help avoid individual "blind spots" and keep the project generally on track, we usually don't have a person both author a change and review/merge it. This is a guideline, not a rule, and a degree of pragmatism is appropriate; small and obvious fixes might be reasonable for an experienced maintainer to make unilaterally, and decisions with larger scope might want unanimous agreement from all maintainers.
Bugs in existing functionality usually take precedence over addition of new functionality. Context-switching should also be taken in to account though, for example if a feature adding PR is nearly complete, and merging it won't interfere with work on another bug, it might make sense to finish the PR before starting on the bug.
Development on a functionality within the project is often driven by just one or two contributors, but a user of the project will use many functionalities across the project. So, when adding functionality, it should aim for consistency with the rest of the project.
The project history represented in Git is a valuable resource, and part of that utility comes from the commit messages which help maintainers of both atsamd-rs and dependent crates understand changes. Writing concise messages can be a challenge, but once the commit is merged in to a protected branch it is essentially immutable.
- Summary line should fit in 50 characters, use the body for longer explanations when needed.
- Use Conventional Commits formatting. We use automated tools to generate changelogs, based on the Git commit messages.
- Please mark breaking changes as such in commit messages using the conventional commit nomenclature (ie, an exclamation mark).
- References to GitHub issues/PRs can be made using #NNN format, in the GitHub UI these will be rendered as links (whether in the summary line or body).
Work on bigger projects can often take a long time, meanwhile development continues in other areas. So, it can become necessary to update a feature branch; Git allows multiple ways of accomplishing this goal, but rebase is preferred to keep a clean history in the feature branch.
While work is progressing, it's often best to make more, smaller, commits; as the feature branch stabilizes, these small commits might make sense to squash together to create larger, but still meaningfully atomic, commits.
Pull Requests in GitHub will trigger CI checks, the requestor should ensure that CI checks pass before waiting on review/merge.
We often use squash-merge, which defaults to using the PR title as the merged commit message. So, it can help if PRs for branches with multiple commits use a title that conforms to the Git commit message guidelines.