-
Notifications
You must be signed in to change notification settings - Fork 230
Get started contributing
Welcome to the SoCo project. We are really glad that you find it interesting and that you might consider contributing to it. All SoCo development is being done by volunteers in their spare time, so all contributions are most welcome. In order to make it as easy for you to contribute as possible, please read the brief instructions below.
If you don't already know what you want to do, you can search the issues for the "Help wanted" label. There, we are looking for new contributors to help us out with relatively small tasks. The issues marked with "Byte size" require small code changes, so they might be the right subject for a first contribution.
No matter if you have already got a subject in mind, or would like to work on one of the items that has already been requested, please consult the code documentation to see what is already implemented and the issues list to see what is being worked on right now. If you want to help with one of the items already in progress please contact the appropriate contributor.
If you are planning a large feature addition, please feel free to open an issue and ask for feedback on the structure you propose for this new addition. If you are planning to make significant structural changes to the existing code please do open an issue and ask for feedback before you start the implementation.
SoCo uses the general github workflow, which is at the core of the following procedure
- Fork the code, to get your own SoCo repository to work on, on GitHub. (Help).
- Clone your code repository, to get a local copy to you computer of you SoCo repository. (Help).
- IMPORTANT! Create a named feature branch for you work. This step will create a special branch for your new code. This will make it a lot easier to work with in the rest of the process. (Details and help)
- Make the changes and commit them in appropriate chunks. Push you changes to your own SoCo repository as often as you wish. Remember to document your code on a level roughly matching the rest of the code.(Help).
- Run you code through some code checkers before your last commit and push. (Optional, see below)
- Make a pull request and wait for feedback. (Help on pull requests)(Why feedback)
- Review the feedback given on the pull request and, if necessary, implement the required changes.(Why feedback)
- Watch the code get pulled and enjoy having contributed to SoCo.
Feature branches are an incredibly useful way of compartmentalizing your work. The idea quite simply is that you create a one new branch in your github repository for each item (e.g. bugfix, refactoring or new feature) that you want to work on. To users of older version control systems this will feel unnatural, because in those systems working with branches was so cumbersome and so much "heavy lifting", that you only made them when you had to, e.g. for different versions of the software. But in git making, shifting and merging branches is so easy and cheap (fast) to do, that we do it all the time ;). The advantage of having a branch for each feature is, that you can easily work on different items at once. E.g. if you find a bug while implementing a large new feature and you would like to have this bug fixed right away, then you can simply start working on a bug fix in a different branch, without having it mixed with your other work.
But where feature branches are really incredibly useful is in the pull request and feedback phase. When you make a pull request, what you are actually asking, is to have the main project pull from your branch, not to have specific commits pulled, i.e. the pull requests follows the branch not the commits. This means that if you want to add some changes to your pull request, e.g. to include some of the feedback you got, the only thing you need to do is to commit the changes in the branch that you asked to have pulled (i.e. your own branch) and they will automatically become part of the pull request. Note that this mechanism will work on any branch and therefore also on your master branch, so using this functionality will not require feature branches, but doing it while working on several different topics will. Using only the master branch you will essentially lock your repository to work only on a single item.
If it has not already been done, we will ask you to break you pull request up into different subjects if it logically consist of such, so you might as well break it up before you start.
Enough talk, lets see it in action. To create a feature branch make the following steps. Make sure that you have an remote upstream location defined for this repository:
git remote -v
origin https://github.com/KennethNielsen/SoCo.git (fetch)
origin https://github.com/KennethNielsen/SoCo.git (push)
upstream https://github.com/SoCo/SoCo.git (fetch)
upstream https://github.com/SoCo/SoCo.git (push)
Notice the upstream reference to this repository. If that is not present, add this upstream location per the instructions on this page. After this make sure to fetch the latest upstream code:
git fetch upstream
If you check all the available branches you should now see the upstream branch appear in the list:
git branch -a
master
* unittest
remotes/origin/HEAD -> origin/master
remotes/origin/master
remotes/origin/unittest
remotes/upstream/master
(you can also tell that I was working on a feature branch called "unittest"). To make a new feature branch, start by checking out the upstream master branch
git checkout upstream/master
Note: checking out 'upstream/master'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
git checkout -b new_branch_name
HEAD is now at c69e3ea... Merge pull request #6 from daubman/safe_encode
It lets you know that you are checking out an upstream branch and in the end it tells you what the last commit made to this branch was. Now to make the feature branch, using this branch as the starting point, execute the following command:
git checkout -b name_of_fancy_new_experimental_feature
Switched to a new branch 'name_of_fancy_new_experimental_feature'
And if you execute:
git branch -a
master
* name_of_fancy_new_experimental_feature
unittest
remotes/origin/HEAD -> origin/master
remotes/origin/master
remotes/origin/unittest
remotes/upstream/master
you can see that you have indeed created a new feature (for your "fancy new experimental feature") and, as git tells you, switched to it (notice the * next to it). Now you can switch between these branches with git checkout, work on any branch that you want and the first time you push from your new feature branch it will also appear in on the github webpage, from where you can also make the pull request when you are done.
If you have any questions about this, feel free to open a new issue about it or ask it in the #soco IRC channel on freenode. It is much better to get it right from the beginning.
There exists several programs to help check Python code against code guidelines and for errors. Coding style guidelines such as pep8 help to ensure consistency and increase readability. The SoCo project employs 3 different code checkers where possible:
pep8 can be regarded as the bare minimum, it contains conventions that really should be followed. Pylint is a more of a code analysis tool, and besides errors it will also give a lot of advice about things that maybe designed badly etc. These advice are just that, advice, and they not not be followed blindly. There can be good reasons not to follow them (like many of the R09?? messages) and maybe one that is flat out wrong (W0142) depending on your view. But in general there are a lot of good advice to be had, so think before disabling messages.
All of the code checkers can be run with the pychecker scripts (.sh and .bat depending on platform) from the dev_tools folder. These scripts are also designed to specifically only show the messages, and therefore they can, along with an appropriate filter, be used to highlight errors in Python-editors and Python-IDE's, like e.g. shown here for geany and emacs.
Please check the output of these code checkers before submitting a pull request and if in doubt just ask for help.