Add New Page: You are not allowed to add pages Select section/namespace. New page title.

Github Workflow

Given the flexibility of development with git, it's worth codifying some best practices for Commotion. Note that this document uses 'project' to refer to a Github project (individual repository holding a specific component of Commotion) and not to the Commotion Project as a whole. This process is meant to be flexible, and will evolve over time as we refine our workflow as a team. It is primarily based on Github Flow (, with the addition of some release handling.


Here are the chief guidelines for development best practice:

* All development takes place in feature branches: Before you start any development, create a descriptively-named feature branch and do your development there. This development should ideally be constrained to one feature or task (or closely related set of feature and tasks). If you want to do work on another feature, create a new branch. Commit all the time, push frequently. GOOD BRANCHES: dbus-support, fix-bug-###, new-route-api BAD BRANCHES: stuff, joshsbranch, development, general-cleanup, plugins-and-apis-and-comments

* When your code is ready for review, submit a pull request against master: Pull requests are part of the code review process. Generally, you should not merge your own pull requests. The maintainer of the particular project is responsible for making sure that pull requests get reviewed. If the maintainer is not available, the lead developer can take that role. There is some leeway on the state of the code you submit for a pull request; you should not be requesting a pull for broken code, but if you're working collaboratively with others then you might choose to submit code that is not intended as the final version, for comment as part of the pull request/code review process. Code should not be merged into a project without the signoff of either the maintainer or the lead developer.

* Only working, tested code should end up in master: Theoretically, everything in master should be deployable.

* Tag releases according to Semantic Versioning: All releases should be tagged, and tags should follow SemVer ( Read and understand that document. You are encouraged to tag patch revisions as often as you feel necessary, and to sketch out a rough roadmap of your individual project to manage other release versions, with the aid of the lead developer.

Stable Branches

Not all projects may require stable branches. If it's a relatively stable project, then you might not need to maintain multiple branches, and can just get away with tagging. However, sometimes you may need to maintain a separate, non-breaking branch of the project.

When to create a stable branch?

* If your project is under rapid development and has a high chance of having breaking changes, create a stable branch.

* If your project has different upstream dependencies (for instance, is against a different version of OpenWRT than the last release) that break things, create a stable branch.

How to create a stable branch?

The recommended naming convention is based on SemVer. Tags and branches are both references, so they can't have the same name. You may, however, want to be able to reference the version at which you first branched. So I recommend tagging with a .0 patch version for your new branch. EXAMPLE: You are currently introducing new internal functionality that requires incrementing from 0.1 to 0.2, but it will break other external dependencies. You decide to create a stable branch. If you haven't tagged 0.1 yet, tag 0.1.0 at the branch point and then create a 0.1 branch. Continue 0.2.x development on master, and any bugfixes will get tagged on the 0.1 branch (0.1.1, 0.1.2, etc.). If you already have a 0.1 tag, just create a new patch version and branch there, and continue tags on that branch.

How to use stable branches?

* Merge or cherry-pick fixes back to stable branches: If you have bugfixes that affect stable branches, make sure those commits get merged (if there are multiple commits and it's feasible), or cherry-picked (probably if there is just one or a short selection of commits) into the stable branch.

* Changes that only affect stable branches: If you have critical bugfixes for functionality that has been deprecated in the master branch, create a feature branch off of the stable branch instead of master, and follow the normal pull request process to merge it back in.