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 `devz, and should be accompanied by version tags.

• 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 PRs sitting open for too long. if they require substantial work or discussion, consider taking some of the remaining work outside;

always prefer to rebase instead of merge, especially on currently-active PR branches, to avoid repetitive RPR commit logs full of the same commits from their parent project.

[... more to come? suggestions welcome]