cacert-policies/README.md

# 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.

## Markdown

New documents should be written in Markdown syntax. Markdowns goal is to
provide a human readable and writable syntax that can easily be transformed to
representations in several output formats.

We use the [CommonMark](https://commonmark.org/) variant of Markdown with the
[table extension](https://github.github.com/gfm/#tables-extension-). CommonMark
is well supported in Markdown libraries and conversion tools. The
code.cacert.org system can render CommonMark Markdown documents to HTML
allowing for easily accessible previews.

### Recommended tooling

To preview Markdown in several formats (HTML, PDF, Office documents) you can
use [Pandoc](https://pandoc.org/) which is packaged for multiple Linux
distributions and has installers for Windows and MacOS.

As Markdown is a plain text format you may use any text editor like Vim,
notepad++ and a lot of alternatives.

If you prefer a live preview and some more assistance you may use a more
heavyweight tool like Visual Studio Code or any of the JetBrains IDEs like
PyCharm.