-
Notifications
You must be signed in to change notification settings - Fork 3
Contribution Guide
To contribute to the Cloudnine project, please follow the procedure below every time you make a contribution. This helps ensure that our code is of a high quality and that everyone is on the same page.
Note that the instructions below assume you are using the command-line Git program. Some may find it easier to use a graphical tool instead. SourceTree is a good option. (Although, you should still have the command-line program installed, even if you are using a GUI tool.)
If you haven't already, follow these instructions to set up the development environment on your local machine.
Before you start making changes, you need to document your planned work in an issue. Click the "Issues" tab at the top of this page and find the relevant issue. Then publish a comment indicating your intent to work on the issue and assign yourself to the issue, if you aren't yet assigned.
If a relevant issue doesn't currently exist, you need to create a new one. Be sure to mark the issue as either a "bug" or an "enhancement" and attach any other labels as required.
You may also need to move the issue to a new column on the project board for the current sprint. Click the "Projects" tab above, select the project board for the current sprint and then verify that the issue is in the correct place on the board.
All work should be done in a new branch. Never make changes directly to master. While Git will let you commit to master on your local machine, this will create problems later when you try to push your changes to the remote repository (GitHub branch protection is turned on, so you will get an error if you try to push changes directly to master).
First, check if a branch already exists for the issue. If it does, switch to it by running git checkout TOPIC-BRANCH where TOPIC-BRANCH is the name of the branch.
If a branch for the issue has not yet been created, create a new branch and switch to it by running git checkout -b TOPIC-BRANCH where TOPIC-BRANCH follows the following format:
- For an enhancement:
enhancement/ISSUE-NUMBER - For a bug fix:
bug/ISSUE-NUMBER
ISSUE-NUMBER should be replaced with the number of the issue in question.
Make any changes you need to make to implement the feature or fix the bug. Changes should be fairly small and incremental: try and break a task into subtasks and then work on one subtask at a time.
Once you've completed a subtask, commit your changes.
First, make sure you are on the correct branch by running git status.
Next, stage your changes by running git add FILE where FILE is the name of the file that will be committed. You can also run git add . to stage all files, but you should carefully check each file to ensure only the desired changes are staged. You can check to see which files are staged and which aren't by running git status again.
Once you are happy that the correct changes are staged, run git commit -m "#ISSUE-NUMBER: SUMMARY" where ISSUE-NUMBER is the number of the issue you are working on and SUMMARY is a short description describing the change.
SUMMARY should always be less than 72 characters and written in the imperative mood, meaning that it is written like a command is being given (e.g. use verbs such as "Add" and "Fix" instead of "Added" and "Fixed").
For example, if you made a design change discussed in issue 44, you might use the following command:
git commit -m "#44: Change the colour of the login button"
If you need to add more information to a commit, run git commit without any arguments. This will open a text editor for you to enter a longer commit message. The first line of the commit message should be a 72 character summary of the commit.
For tips on writing a good commit message, refer to this blog post.
When you are ready to make your changes available to the other team members, you can push your commits to the remote repo:
git push -u origin TOPIC-BRANCH
...where TOPIC-BRANCH is the name of the branch you switched to in step 2 above.
Repeat steps 3-5 until you've made all the changes necessary for the issue in question. If other team members have been working on the same branch, make sure they have finished making their changes (commenting on the issue is a good way to do this) before proceeding to step 7.
Once you are satisfied with your changes (and the changes of anyone that has been helping you with the issue), make sure that all changes have been committed and all commits have been pushed to the remote repo. Then, create a new pull request:
- Go to the branches page and click the branch you've been working on.
- Click Create pull request.
Each sprint you will have a different person in the team act as your reviewer. The reviewer's job is to check your code and make suggestions for improvements. Be sure to assign the pull request to your reviewer and add any details that would be helpful to the reviewer. It is also important that you add the issue that the pull request addresses as a "linked issue" to the pull request (this way, the issue will automatically be closed when the pull request is approved).
If your reviewer is unavailable for several days, you can ask someone else in the team to review your code instead.
When your reviewer is happy with your changes, they will approve the pull request and merge your changes into the master branch.