Code contributions by the community are always encouraged and valued. This page describes how best to work with the projects hosted by BrewTroller.
Note: BrewTroller project hosting is on GitHub: https://github.com/brewtrollergit
Each code project has it's own issue log. For non-developers, the issue log can be used to notify the development team of issues that require attention. For those contributing code, the issue log also provides a conduit to submit patches to the project maintainer.
General guidance for creating issues:
- Verify the issue has not already been fixed in a newer release
- Avoid creating duplicate issues by reviewing existing issues
- When attaching a patch to an issue follow the procedures below to create the patch file
BrewTroller uses Git for version control and hosts its projects on GitHub: https://github.com/brewtrollergit
If you are just getting started with Git you may benefit from reading Pro Git by Scott Chacon (freely available online).
Each project should have two primary branches: master and develop. Master should always represent deployable, stable code. Code in develop should always compile but is not considered stable for general use. New features are typically added to branches made from develop. Urgent hotfixes to be immediately deployed are applied to branches from master. The project maintainer will also need to apply the hotfix to develop so that fixes are not reverted with future releases.
The first step to creating a patch is to clone the code repository you will be modifying. Cloning a repo makes a complete local copy of the repo including all its history. You only need to do this once for a project. You can udpate your local clone by doing a pull from the remote 'origin' (default remote created with clone command).
You will need the Git URL to clone the repo. The easiest way to obtain the URL is to click Browse Repository on the project's development page. The web frontend for the repo will provide its URL.
The following is an example URL for the BrewTroller project:
To clone this repository you would type the following command:
git clone https://github.com/brewtrollergit/brewtroller.git BrewTroller
This clones the repository at the specified URL into a subfolder of the current working directory called 'BrewTroller'.
Note: Arduino requires the folder containing the sketch name to match the primary sketch file. For BrewTroller this is a folder called BrewTroller containing BrewTroller.pde.
Each time you create a new patch you should start with a new local branch of master (critical hotfix) or develop (next release) as appropriate. If you are working from a clone you created previously make sure you perform a Pull to update your clone.
The checkout command is used to switch you working directory to a specific branch. a -B option allows you to create and switch to a new branch. You can also supply the name of the parent branch you want to branch off.
git checkout –B Patch-123456_Fix_Some_Problem master git checkout –B Feature-My_New_Feature develop
As you develop you commit your changes to your local branch. It is generally recommended to break up larger changes into several smaller commits were logically possible.
When you have completed your code you can package the changes as a patch file to attach to a new or existing issue:
git format-patch master --stdout >Patch-123456_Fix_Some_Problem.patch git format-patch develop --stdout >Feature-My_New_Feature.patch
You may want to apply a patch that has been posted by another user that has not yet been committed to the repository. First, follow the instructions above to clone the project repository. Save the patch within your working directory and use the following syntax to apply the patch:
git apply Patch-Some_Interesting_Fix