diff --git a/README.md b/README.md new file mode 100644 index 0000000..47e2cea --- /dev/null +++ b/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.