-
Danny McDonald authoredDanny McDonald authored
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:
-
clone the repository to your local machine:
git clone https://gitlab.uzh.ch/lit/digizeit
-
checkout (create and switch to) a new branch:
git checkout -b typo-fix
(create a branch calledtypo-fix
- Modify the checked-out branch in any way you like (in this case, by fixing some typo you found)
- Add the changed files to staging area:
git add README.md
(to add changes made toREADME.md
) - Commit the changes to your local repository with a message
git commit -m "fixed the typo in the readme"
- Push changes to GitLab, which will create the
typo-fix
branch on the remote:git push
- Use GitLab website interface to make a merge request from
typo-fix
intomaster
- Changes will be reviewed, commented on and accepted/rejected by an admin
- 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).
- Click the fork button in GitLab to make a version of the project under your namespace
- Clone the forked repository;
git clone https://gitlab.uzh.ch/my-username/digizeit
- Modify the master branch in any way you like (i.e. fix the bug you found)
- Add the changed files to staging area:
git add code/buggy.py
(to add your fixes to the buddy Python file) - Commit the changes to your local repository with a message
git commit -m "fixed the bug in buggy.py"
- Push changes to GitLab, which will show up in your work
- Use GitLab website interface to make a merge request from your fork's
master
into the original (upstream)master
- Changes will be reviewed, commented on and accepted/rejected by an admin
- 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
, thengit 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!