From db0346d8a9c0b9e82956a85134f891502cea9bf2 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sat, 24 Feb 2024 14:03:16 +0100 Subject: [PATCH 1/3] Add Git workflow documentation --- README.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 README.md 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. From 2ffc4a51612d1f1ded09b812493c7ad2be4fb842 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sat, 24 Feb 2024 14:06:06 +0100 Subject: [PATCH 2/3] Add .gitignore and .gitattributes This commit adds basic .gitignore and .gitattributes files to ensure normalized line endings and avoid adding editor configuration or temporary files. --- .gitattributes | 2 ++ .gitignore | 2 ++ 2 files changed, 4 insertions(+) create mode 100644 .gitattributes create mode 100644 .gitignore diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..506833b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +*.md text eol=lf +*.html text eol=lf diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..468a0f1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.*.swp +/.idea/ From b4947436f91fe1ccfafb487269c726f9911f3712 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sat, 24 Feb 2024 14:22:54 +0100 Subject: [PATCH 3/3] Add a section about MarkDown This commit adds a short documentation about Markdown/CommonMark and tool recommendations. --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index 47e2cea..c5fe130 100644 --- a/README.md +++ b/README.md @@ -139,3 +139,28 @@ 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.