git style

github workflow and guidelines

branches

currently, norns is in a closed, alpha state of development. the only persistent branch in the repo is named dev. once the software is ready for a broader range of beta testing, we will create a master branch and begin proper semantic versioning.

• at that point, changes to master should only be made by merging from known-working states of dev, and each change should be accompanied by a version tag and probably a release package.

• a branch called work may exist at times. if it exists, it should be considered in a non-functional state; its purpose is to troubleshoot or share work-in-progress across machines.

• feel free to create other branches for features and bugfixes. for now i don't think we need a naming convention for branches [???]

pull requests

any changes to dev should be made through a PR. the comparison branch can be on a fork or on the upstream (currently catfact/norns.) the comparison branch should be rebased against dev to avoid duplicated commit logs. for c code, it's also a good idea to run uncrustify.sh.

dev is "protected", meaning that PRs cannot be merged without a review or an admin override. the purpose for this review step is not so much to head off bugs at this point (though it may help) but simply to give all developers a better chance of keeping up with incoming changes.

if a PR owner requests you for a review, and you consider the changes reasonable, then you are free to merge the request (though not obligated.) if you perform a review, please do check the "files changed" view and note anything that seems questionable. if you don't want to take the time, feel free to request a different reviewer.

this usage of the "review" process isn't so much to perform full code reviews and catch bugs (though that would be nice) but to ensure a bare minimum awareness of changes to the codebase by more than one person.

other suggestions

• it's unwise to leave unmerged PRs sitting open for too long; they quickly get stale and out of sync.

• that PRs that are intended for discussion of work-in-progress should be clearly labeled with "DO NOT MERGE" or similar. this should a temporary situation. if it goes on long enough that other changes are coming into dev, its time to close the PR, rebase and reopen. remember that closed PRs are still available as discussion pages and can be linked back into issue pages.

• generally prefer to rebase over merge when applicable, as it tends to keep the commit history more relevant and less repetitive.

[... more to come? suggestions welcome]