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.
  • 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.


  • No labels