CONTRIBUTING.md

Contributing guidelines

Everyone is welcome to add content to this repository. In fact, at various points in the semester, contributing will be part of your homework!

The simplest ways to contribute are by adding to the Wiki and Issues pages. These actions can both be completed using nothing but your browser.

However, one key outcome of this course is that you'll learn how to use Git to pull and push changes to repositories like this one. In Week 2, we will run a workshop that will set up your machines for Git use, and teach you basic Git workflows.

There are two main workflows for adding to/modifying a git repository: via branch, and via fork.

Branching

By default, you are looking at the master branch of this repository. However, other branches (versions) can also be created, and the changes from one branch can be merged into another (typically, into the master branch). The basic steps are:

1. clone the repository to your local machine: git clone https://gitlab.uzh.ch/lit/digizeit
2. checkout (create and switch to) a new branch: git checkout -b typo-fix (create a branch called typo-fix
3. Modify the checked-out branch in any way you like (in this case, by fixing some typo you found)
4. Add the changed files to staging area: git add README.md (to add changes made to README.md)
5. Commit the changes to your local repository with a message git commit -m "fixed the typo in the readme"
6. Push changes to GitLab, which will create the typo-fix branch on the remote: git push
7. Use GitLab website interface to make a merge request from typo-fix into master
8. Changes will be reviewed, commented on and accepted/rejected by an admin
9. Once finished, you can delete your branch: git branch -d typo-fix

Forking

When you fork a repository, you copy an entire project, potentially including all the branches of the original project. This is the workflow you need if you do not have write access to the repository you are modifying (i.e. if you are submitting a bugfix on someone else's project).

1. Click the fork button in GitLab to make a version of the project under your namespace
2. Clone the forked repository; git clone https://gitlab.uzh.ch/my-username/digizeit
3. Modify the master branch in any way you like (i.e. fix the bug you found)
4. Add the changed files to staging area: git add code/buggy.py (to add your fixes to the buddy Python file)
5. Commit the changes to your local repository with a message git commit -m "fixed the bug in buggy.py"
6. Push changes to GitLab, which will show up in your work
7. Use GitLab website interface to make a merge request from your fork's master into the original (upstream) master
8. Changes will be reviewed, commented on and accepted/rejected by an admin
9. Once finished, you can delete your fork on GitLab. Otherwise, if you want to make more changes still, you will want to update your fork to match the latest upstream master branch: git fetch upstream, then git merge upstream/master

This is all quite complicated at first, but after a little while, it will start making more conceptual sense. You might even find it fun!

Good luck!