Using GitHub

GitHub code management

To ensure an uncomplicated collaboration on GitHub we have formulated some general guidelines for working with Git.

1. For each developer development occurs on a local clone of the repository and is pushed to a development branch not the master branch
2. Each user works on their own development branch. They should have a branch for each feature they are wishing to implement. This branch should contain the name of the user and also some information about the type of feature that is being implemented. After completing a feature and merging it this branch should be deleted to keep the number of open branches limited to active ones.
3. A development branch is only merged with the master branch when it has been tested and deemed stable. This is always done using a pull request and needs to be reviewed before merging.
4. Commits should always be given with an informative commit message e.g. 'besca initial commit of source code', 'update besca documentation', etc.
5. New features that are being implemented need to be documented in git issues and assigned to the user working on them to ensure that everyone is up-to-date on what is being worked on.

An adherence to these guidelines will help ensure that we do not hinder each others work and work together productively.

creating a local copy of the repository on your system

1. navigate to the location on your hard drive where you want to keep the local copy of the repository
2. Clone the git repository into your repository. git clone https://github.com/bedapub/besca.git

This automatically creates a directory called besca in the directory you cd'd into previously.

checking out a branch

On besca, we have three different branches including master and gh-pages. The gh-pages branch is only used for the documentation and should only be checked out when trying to build a more up-to-date version of the documentation. The process for checking out any of these branches is the same. Simple replace branch_name with the correct name of the branch.
git checkout branch_name

Entering git status will always tell you which branch you have currently checked out!

pushing changes back to the checked out branch

After developing new code you may wish to push your changes back to the dev branch on GitHub to store them for later. This ensures that 1. you have a backup of your code and 2. you can revert back to the old versions in case something goes wrong during development. This procedure works the same for all branches but in general, you should only be developing on the dev branch!

1. Check git status
   This lets you see which files have been changed and helps you ensure that the correct branch is checked out.
   git status

2. add the files you wish to commit. git add [file list]. (Alternatively, you can also use git add --all if you wish to commit all files that have changed.)

3. commit your changes
   git commit -m 'informative commit message'

4. Push your results
   git push branch_name You will be asked to enter your username and password for GitHub.

merging your dev branch back into the master branch

Once you have ensured that your development version is stable (see :ref:here <testing-besca-features>) and want to make it available to everyone else you can merge your dev branch into the master branch. Before doing this you should ensure that all of your changes in the dev branch have been :ref:committed and pushed <testing-besca-features> to GitHub.

1. Navigate to https://github.com/bedapub/besca/pulls <https://github.com/bedapub/besca/pulls>_ and open a new pullrequest
2. have someone review the pull request
3. merge the pull request