Add Git workflow documentation

README.md

@@ -0,0 +1,141 @@
+# The CAcert policy repository
+
+This repository contains work in progress policy documents for CAcert.
+
+## Getting started using Git
+
+We use [Git](https://www.git-scm.com/) for working with this repository. Git is
+a free and open source distributed version control system.
+
+### Installing Git
+
+To work with Git you need a piece of client software. Git is available for all
+major operating systems. On Linux systems Git is available from your
+distribution's package manager and can be installed using something like
+
+```shell
+# install Git on Debian based systems
+sudo apt install git
+```
+
+or
+
+```shell
+# install Git on Fedora based systems
+sudo dnf install git
+```
+
+For Windows or MacOS you should use the binary installers from the [Git
+Download Page](https://www.git-scm.com/downloads).
+
+### First steps with Git
+
+Open a Terminal window (Linux and MacOS have default terminal applications, on
+Windows you might want to use the *Git bash* that comes bundled with the Git
+client installation).
+
+Tell Git who you are and what email address you would like to use. This
+information will be put in commits you will do later.
+
+```shell
+# Tell Git who you are
+git config --global user.name "Your Full Name"
+git config --global user.email "yourname@cacert.org"
+```
+
+### Get a clone of this repository
+
+A local working copy is called a *clone* in Git terminology. Run
+
+```shell
+cd $HOME/where-your-projects-live
+git clone https://code.cacert.org/cacert/cacert-policies.git
+```
+
+to get your local copy.
+
+### Update your local copy
+
+If you have not worked on your copy for a while you can update it with the
+following commands:
+
+```shell
+cd $HOME/where-your-projects-live/cacert-policies
+git pull -r
+```
+
+### Making changes
+
+If you want to make changes to the content of the repository, working on a Git
+branch is recommended. You can have multiple branches in your local Git clone
+and can switch between these.
+
+```shell
+cd $HOME/where-your-projects-live/cacert-policies
+# create a branch for your work
+git checkout -b some-topic-you-will-work-on
+```
+
+You can then make changes in the files in your working copy as you like. You
+can also add new files. When you are satisfied with what you have, you can add
+the changes to Git's staging area (in some documents this is also called the
+*index*):
+
+```shell
+git add .
+```
+
+You can show the status of your local copy using
+
+```shell
+git status
+```
+
+If you would like to remove a file you can run
+
+```shell
+git rm the-file-you-do-not-want-anymore
+```
+
+To publish your changes for review you need to create a commit and push your
+branch to the origin repository.
+
+Please make yourself familiar with [how to write good Git commit
+messages](https://cbea.ms/git-commit/). It will make the life of your future
+self and of other contributors a lot better.
+
+```shell
+# Make a commit
+git commit -m "Add inspiration quotes
+
+Fixes #1"
+# Push your branch to the origin repository
+git push origin some-topic-you-will-work-on
+```
+
+You may repeat the edit, commit, push cycle multiple times and finally create a
+pull request by clicking on the link in the output of the git push command.
+
+### Switching to another branch
+
+If you wait for a review on your pull request or want to work on a different
+topic you can switch to the main branch and start a new branch from there as
+described above.
+
+```shell
+git switch main
+```
+
+### Recommended reading
+
+Git comes with a very comprehensive built-in help. Help can be retrieved using
+
+```shell
+# get help for Git as a whole
+git help
+# get help for a specific command, in this case git switch
+git help switch
+```
+
+If you would like to dive deeper into Git you can read the free [Pro Git
+book](https://www.git-scm.com/book/) on the Git website.