DRAFT !!!
General contribution process
Fork the repository and work on a personal branch.
Use personal feature branches, never commit directly to master branch
Rebase before creating Pull Request to keep history clean and avoid merge conflicts.
- avoid merge commits in PRs
Keep changes focused: One PR should address one topic or issue only.
Avoid mixing refactors and features in a single PR unless tightly coupled.
Commit message guidelines
Use meaningful commit messages:
Format:
subsystem: short description
Example: "
boot: Fix buffer overflow in flash driver"
Write in imperative tense: e.g., "Fix bug" not "Fixed bug".
Include context and rationale in the commit body when necessary.
Reference Github issues using
Fixes #123
Avoid unrelated changes in commits. Split large commits into logical units.
- Commit message should follow "What and Why, not How" principle
- Good example:
scheduler: Fix missed task execution due to race condition
Under high interrupt load, tasks were occasionally skipped
because the ready queue wasn't properly locked during updates.
This fixes #123
- Bad example
fix bug in scheduler.c
change while loop to for loop and added a lock
Code & Pull Request Structure
Follow existing file and module organization.
- Follow the project’s coding conventions
- See CODING_STANDARDS.md for details
- Code style (and licensing) is validated by automation on PR submission
Clearly note in PR message if third-party dependencies are being introduced
Avoid breaking public APIs; discuss major changes via a proposal.
Separate functional changes from formatting in different commits.
- Dedicated PR with code cleanups (concurrent to one with feature) makes it simpler to get code merged
If possible include tests for new features and bug fixes.
Document new APIs or modifications in the appropriate header and markdown files.
Use compile-time flags (syscfg.yml) and configuration macros (MYNEWT_VAL_*) to control optional features.
Do not introduce compilation issues in Pull Requests
each commit should compile (even if it is non-funtional), this is to make bisecting simpler
Do not include commits with fixes to commits in same PR
- if fix is needed it shall be squashed to original commit (`git rebase --interactive master` may be helpful)
Pull Request Submission
Title your PRs clearly and concisely.
Describe the purpose and scope of changes in the PR description.
Include testing details: what was tested, how, and results.
- run "
newt test all"
before submitting.
- run "
- Mark as draft if the PR is not ready for merging.
- tag relevant people in draft if want to get early feedback
Avoid large PRs unless unavoidable; split them for clarity and easier review.
Rebase interactively to squash or reorder commits before merging if needed.
- Fix any issues reported by automated integration tools
- in particular build errors may block PR merging
Communication
- "Be Excellent to Each Other"
- Treat everyone with respect and kindness, whether a newcomer or a long-time maintainer.
- Assume good intent. People contribute with the goal of helping, even if their first PR or comment isn't perfect.
- Be patient with questions and mistakes, especially from newcomers. Point them to helpful resources rather than dismissing their efforts.
- Avoid sarcasm, dismissiveness, or personal attacks, these can discourage future contributions.
- Give constructive feedback, focusing on the code or problem
- Be mindful that many contributors are non-native English speakers
- Favor clarity over cleverness in code comments, commit messages, and reviews.
Discuss large changes before starting work.
Use github issues or mailing list for discussion
it is also possible to use Slack for more realtime communication
summarize slack conclusion in github or mailing list if those were also used
Be responsive to reviewer comments and update PRs accordingly
- Don’t expect immediate replies, contributors may be in different time zones or have other commitments.