Zerocat Label Documentation – General infos



* H. Kienle (See source file for contact information.)  
* Kai Mertens (See source file for contact information.)


(See source file for copyright information.)



Zerocat Label Documentation ships copyrighted work.  
See [AUTHORS][] for a list of people which have contributed.

Zerocat Label Documentation is free software. It makes use of free software
approved licenses only and should be freely distributable:

* [GNU General Public License][GNU GPL]
* [GNU Free Documentation License][GNU FDL]
* [CreativeCommons Attribution-ShareAlike License][CC BY-SA]

Authorship, copyright and license information may be provided in more 
detail on a per-folder and/or per-file basis. Check the sources.

Please report a bug if you find the distribution hindered by any
obstacle. See [Zerocat Website][] for contact information.


[AUTHORS]:                ../doc/AUTHORS.md
[GNU-GPL]:                ../doc/GNU-GPL.md
[GNU-FDL]:                ../doc/GNU-FDL.md
[CC BY-SA]:               https://creativecommons.org/licenses/by-sa/4.0/
[Zerocat Website]:        http://www.zerocat.org/


(See source file for copyright information.)



Project Goal

The goal of Zerocat Label Documentation is to provide you with some
general information about the label itself, in opposite to project
specific infos.


All paths within this document are relative in respect to the original
location of this source file, which is located in the project’s `doc/`


If you are on GNU Guix System, create your environment:

        guix environment --pure -m ../guix/manifest.scm

Otherwise, check the manifest file and install the listed packages with
the package manager of your distro. Adapt package names as required.

Make Documentation

To build the documentation, type:

        make -C ../doc

To get a full list of available targets, type:

        make -C ../doc help

Note we are currently migrating the documentation system. For the time
being, you might still generate the obsolete documentation using

        cd ../doc-doxygen


Once you have contributed, add yourself to [AUTHORS][].

### Documentation Files

In order to enrich this documentation:

* add more `*.md` markdown text files to `../doc/`
* maintain copyright footer within new files
* add more folders, images or other files

... and adapt `../doc/Makefile` to produce nice output.

In case more tools are needed, don't forget to update

### Shell Scripts

If you intend to write shell scripts, use this skeleton to make them
work for GNU Guix:


        # Re-exec if we are not using Bash or are using Bash in POSIX mode.
        if [ -z "$BASH" ] || [ "$BASH" = "/bin/sh" ]; then
          bash=`command -v bash`
          if [ -z "$bash" ]; then
            echo "Couldn't find Bash, sorry!"
            exit 1
            exec "$bash" "$0" "$@"

        # We're using Bash now.
        set -o errexit
        set -o nounset
        set -o pipefail

        # Your code goes here ...

### Code Files

This project may ship non-code, graphic sources, which cannot be
covered by the standard GNU General Public License. The license header
for code source files thus has been adapted accordingly, please use it
if you intend to write code:

        Zerocat Label Documentation --- General infos

        Copyright (C) 2021  Authors of Zerocat Label Documentation

        This file is part of Zerocat Label Documentation.

        This file is free software: you can redistribute it and/or modify it
        under the terms of the GNU General Public License as published by
        the Free Software Foundation, either version 3 of the License,
        or (at your option) any later version.

        This file is distributed in the hope that it will be useful, but
        WITHOUT ANY WARRANTY; without even the implied warranty of
        See the GNU General Public License for more details.

        You should have received a copy of the GNU General Public License
        along with Zerocat Label Documentation.
        If not, see <http://www.gnu.org/licenses/>.

Version Tags

Within this project’s git repository, versions are tagged according to
the following pattern:


* major – The resulting product is a major change or upgrade.
* minor – Additional functionality or new features are introduced.
* revision – Bug fixes, minor changes, graphical stuff.


[AUTHORS]:        ../doc/AUTHORS.md
[Git]:            https://git-scm.com/
[Zerocat Team]:   http://www.zerocat.org/team.html


(See source file for copyright information.)


Zerocat Git Repositories

Server Information

The domain names “www.zerocat.org” and “www.zerocat.de” are both pointing
to our server.  
The server’s IP address is “”.

The Git Gatekeeper

Zerocat’s git repositories are hosted by user `git`, and access control
is managed by a gatekeeper. A client can talk to the server’s
gatekeeper using SSH authentication, thus the generation of an
SSH keypair might be required.

### Prerequisites

Please make sure the following programs are availbale on your machine:

* `git` – Distributed version control system
* `openssh` – Client and server for the secure shell (ssh) protocol

Get yourself prepared by studying the output of:

* `man git-clone`
* `man ssh`
* `man ssh-keygen`
* `man ssh-config`

### Generate SSH Keypair

You can generate a new pair of SSH keys by running:

    $ ssh-keygen \
        -t rsa \
        -b 4096 \
        -C "" \
        -f ~/.ssh/my-zerocat-ssh-id

Adapt settings to your needs. This will create a pair of keys – a
secret and a public one, i.e.: `~/.ssh/my-zerocat-ssh-id` and

### Access via SSH-Key Authentication

In case your public SSH key has been deposited on the server, you
might talk to the gatekeeper over `ssh` and use the `info` command to get
a full overview of repositories and of your current access permissions:

    $ ssh -2 -4 \
        -i ~/.ssh/my-zerocat-ssh-id \
        -p 32323 \
            git@zerocat.org info

Note, as default, this would look up your `~/.ssh/id_rsa` file for
authentication, but you specified an individual identity file with the
`-i` option.

The gatekeeper offers some more commands, like:

* `help` (lists all available commands)
* `desc` (describes a specified repository)


    $ ssh -2 -4 \
        -i ~/.ssh/my-zerocat-ssh-id \
        -p 32323 \
            git@zerocat.org desc zerocat/projects/chipflasher

Note the server’s SSH Daemon is listening to port 32323 only.

### SSH Configuration File

The `ssh` client supports a configuration file named `~/.ssh/config`,
where you can manually bundle the required credentials to make things
easier to deal with, e.g.:

    host git-gatekeeper-zerocat
            user git
            port 32323
            identityfile ~/.ssh/my-zerocat-ssh-id
            addressfamily inet

Getting Started with 'Git Clone'

### Private Repositories

    $ git clone ssh://git-gatekeeper-zerocat/zerocat/projects/<project-name>

This will download the repository and sets `origin` to the same used
Now change into the newly created project folder and run `git log`
to see the project’s history.

### Public Repositories

Some repositories are publically accessible without authentication, i.e.:

* zerocat/projects/doc
* zerocat/projects/chipflasher
* zerocat/projects/coreboot-machines
* zerocat/projects/ps2-keyboard
* zerocat/projects/turning-hook

Cloning can therefor be done using the git protocol:

    $ git clone git://zerocat.org/zerocat/projects/chipflasher

These public projects are promoted on our website: [www.zerocat.org][]


[www.zerocat.org]:    http://www.zerocat.org/


(See source file for copyright information.)


Zerocat Git Usage


- Pro Git, Apress, 2nd edition, 2014

    - <https://www.git-scm.com/book/en/v2>
    - <https://www.git-scm.com/book/en/v2/Git-Branching-Remote-Branches#Deleting-Remote-Branches>
    - <https://www.git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging>

- Git from the Bottom Up

    - <https://jwiegley.github.io/git-from-the-bottom-up/>
    - <http://newartisans.com/2008/04/git-from-the-bottom-up/>

- The Thing About Git, explains `git add --patch`

    - <http://2ndscale.com/rtomayko/2008/the-thing-about-git>

- fetch/merge vs. pull

    - <http://longair.net/blog/2009/04/16/git-fetch-and-merge/>

- gitk example run-through: Use gitk to understand git – merge and rebase

    - <https://lostechies.com/joshuaflanagan/2010/09/03/use-gitk-to-understand-git/>
    - <https://lostechies.com/joshuaflanagan/2010/09/03/use-gitk-to-understand-git-merge-and-rebase/>

- How to Write good Commit Messages

    - <http://chris.beams.io/posts/git-commit/>

Configuration Template

To ease collaboration, we would like to suggest the follwing settings
for your Git Configuration. You might place them in the `.git/config`
file of a project’s root folder, or – as an alternative – in your
global Git Configuration File `~/.gitconfig`.


	name		= <your name>
	email		= <your email address>
	signingkey	= <your PGP key ID>
	gpgsign		= true
	editor		= nano
	# git log:
	#   l: log, g: --graph --color,
	#   c: --oneline, s: --pretty=short, f: --pretty=format,
	#   a: --all
	lg		= log --graph --color --decorate
	lga		= log --graph --color --decorate --all
	lgc		= log --graph --color --decorate --oneline
	lgca	= log --graph --color --decorate --oneline --all
	lgs		= log --graph --color --decorate --pretty=short
	lgsa	= log --graph --color --decorate --pretty=short --all
	lgf		= log --graph --color --decorate --pretty=format:'%C(auto) %h %d %G? %aN  %s'
	lgfa	= log --graph --color --decorate --pretty=format:'%C(auto) %h %d %G? %aN  %s' --all
	# git diff:
	check	= diff --check
	default = simple


The `[alias]` section now contains some aliases for `git log`, and
commands like `git lgca` should help you to get a quick overview of the
repository’s history. In case you need to verify authors, use `git
lgfa` instead.

To see whether your changes would introduce misplaced white-space, run
`git check` as an alias of `git diff --check`.

When using GPG-signed commits as suggested by `gpgsign = true` in
section `[commit]`, please check your `~/.gnupg/gpg-agent.conf` to have
a line available which specifies a pinentry program, i.e.:


pinentry-program /usr/bin/pinentry


Some Useful Invokes

They mostly come from reading the "Pro Git" book.

    # get started with a repository
    git init
    git clone

    # show changes
    git diff
    git diff --cached                     # same as `--staged`
    git status
    git status -uno
    git status -s

    # commit changes
    git commit -am "<commit message>"     # fast commit of *all* changes
    git add <file>
    git add --patch
    git commit -m "<commit message>"      # fast commit of *staged* changes
    git commit --no-status
    git commit --uno

    # rename or delete files
    git mv
    git rm

    # work with branches
    git branch                            # list local branches, mark current one
    git branch <a-new-branch>             # create a new local branch, but stay on current one
    git checkout -b <a-new-branch>        # create *and* checkout a new local branch
    git stash                             # push away current changes which might hinder you to checkout elsewhere
    git stash pop                         # pop previously pushed changes

    ## set up new-branch to track remote new-branch
    git checkout new-branch

    ## delete branch upstream
    git push origin :my-obsolete-branch

    ## delete local copies of already deleted upstream branches
    git fetch --prune                     # refers to all local copies of remotes

    # show history of commits
    git log
    git log --pretty=format:"%h %an %s" --graph
    git log --abbrev-commit --pretty=oneline --graph
    git log --abbrev-commit --pretty=medium
    git log -p -2
    git log --follow <filename>

    # git configuration
    git config --list
    git config --add format.pretty oneline
    git remote -v
    git difftool --tool-help

    # show differences between commits/ branches/ tags/ etc.
    # in detail...: git diff <from> <to>
    git diff master documentation
    # in short...: git diff --stat <from> <to>
    git diff --stat <refspec> HEAD    # you can omit 'HEAD'

Roles and Responsibilities

- Project Initiator and Maintainer...
    - performs the merges into `master` or asks contributors to do so
    - pushes branches as a call for contribution

- Contributors...
    - announce their branch and its purpose in advance by mail
    - don't forget to delete their branches in origin when the merge is done
    - or explain shortly why the branch is kept

Workflow: Contributing via branching

### Contributor:

    git branch my-new-branch ; git checkout my-new-branch
    git add new-file-in-branch
    git commit
    git push origin my-new-branch  # Announce this via email
    git branch --set-upstream-to=origin/my-new-branch my-new-branch
    git push origin --delete my-new-branch  # We are done with the branch, delete on server

### Others:

    git pull origin             # Now new remote branches are visible
    git checkout my-new-branch  # Sets up tracking branch (git branch -vv)
    git branch --delete my-new-branch  # We are done with the branch, delete locally

### Project Maintainer:

    git checkout master ; git merge my-new-branch


- gitk (comes with git)

Beyond Git

- git-annex: <https://git-annex.branchable.com/>


(See source file for copyright information.)
(See source file for copyright information.)


Zerocat Markdown Usage

The Original Markdown

The (original) language is described here:

Plenty of variants and extensions are around:

- Doxygen: <http://www.stack.nl/~dimitri/doxygen/manual/markdown.html>
- GitHub: <https://help.github.com/categories/writing-on-github/>
- kramdown: <http://kramdown.gettalong.org/syntax.html>


There a many different translators available.

### CommonMark's cmark

This is a C/C++ implementation with an extensive test suite:

To run it:

    cmark in.md > out.html

### discount

To get something quickly up and running for openSUSE there is the
"discount" package available:

- <https://github.com/Orc/discount>
- <https://software.opensuse.org/package/discount>
- <http://www.pell.portland.or.us/~orc/Code/discount/>

Emacs mode

It consists of a single lisp file `markdown-mode.el` that needs to be
found in the Emacs load path. (Does not work with XEmacs.)


Markdown Styleguide

### Goals

This is supposed to be as brief as possible. The goal is to capture a
minimal subset of Markdown that is sufficent for our needs and is
understood widely by various tools.

### Styleguide

How to write markdown files, some guides:

* Wrap headlines with *two empty lines* before *and* after.
* Justify paragraphs, break long lines.
* Indent/justify text of list items if spread over multiple lines.
* Maintain two spaces at the end of line to force a line break.
* Delete trailing, single spaces.
* Put words that require to be escaped into backticks: `<value>`
* Set paths into code style font, i.e.: `../doc/`
* Use three characters to mark a horizontal rule: `___`
* Mark *italic font* with one asteric: `*italic*`
* Mark **bold font** with two asterics: `**bold**`
* Mark ***bold italic font*** with three asterics: `***bold italic***`
* Maintain a copyright footer, introduced with an horizontal rule.
  Maintain copyright notes without introducing spaces, but with two
  spaces inbetween and at the end in order to force a line break:


        Copyright (C) 2021, 2022  Somebody <Email-Address>  
        ... License Note ...

### Other Styleguides

We can take inspiration from others, for example

- <http://www.cirosantilli.com/markdown-style-guide/>
- <http://tirania.org/blog/archive/2014/Sep-30.html>


(See source file for copyright information.)
(See source file for copyright information.)

Documentation for “Zerocat Label Documentation” as of Tue, 26 Oct 2021 10:06:29 +0200
Repository: git://zerocat.org/zerocat/projects/doc
Version: v0.1.7-45-2e60aa6
Branch: master