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

# install Git on Debian based systems
sudo apt install git

or

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

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.

# 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

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:

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.

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):

git add .

You can show the status of your local copy using

git status

If you would like to remove a file you can run

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. It will make the life of your future self and of other contributors a lot better.

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

git switch main

Recommended reading

Git comes with a very comprehensive built-in help. Help can be retrieved using

# 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 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 variant of Markdown with the table 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 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.