document basic git[hub] workflow

[jelmd]

Summarized the outcome of our discussions wrt. gate keeping and git workflow etc..

[jelmd]

@dannyweldon - can you have a look at it wrt. proper wording, etc. ?

[jelmd]

Thanx a lot @dannyweldon :1st_place_medal:

[dannyweldon]

@jelmd if you have no further commits, shall I just merge this?

And according to this document itself, are we going to need to setup this docs branch to require two approvers? Or, just do that for ksh source only?

Should a separate person do the merge, or should the last person required to approve a PR just do the merge?

Or should someone else

[jelmd]

@dannyweldon yes. Actually @marcastel said he wanna review and try it with this PR, but he is probably too busy to give it a try. So after 6 weeks it is IMHO ok to merge with 1 approval, only (and since this is the doc repo ... ;-) ).

[marcastel]

Correct overloaded. Sorry. Still heavily booked for 10 days or so.

About 50% done. (also wanted to include a extremely simple Makefile-based documentation workflow POC, cf sample output of index page below, @jelmd works are in Community Git-flow)

Feel free to go ahead if delaying is an issue.

[marcastel]

PS. So that you don't get heated up by the HTML rendering. Source files are plain Markdown and the Makefile essentially relies on two utilities ksh(1) and pandoc(1).

Markdown of above Git-flow content portion:

Makefile:

KISS :-)

[dannyweldon]

Hey @marcastel, that looks great, as long as we can just use github markdown and in-place editing, it will make it super easy to contribute.

[marcastel]

Gents. Sorry for the VERY LONG latency. Post-confinement has incurred a lot of overhead work... applying M/M/1 models for Kanban-intensive not fully automated industrial workflow processes. Probably under pressure until both Switzerland and France finally reopen their frontiers (mid June).

I will try to get some work done this weekend. @jelmd work is fine. To be complete, I believe we need a formal practice for commit messages, change logs and release notes. I have drafted something too long to paste here... except perhaps a first attempt at a dictionary of keywords to classify commits.

Cheers, Jean-Michel

keywords:

  - name: chore
    desc: Routine tasks, typically Git maintenance tasks.

  - name: feat*ure
    desc: A distinguishing characteristic of a software item (IEEE 829),
          which primarily targets functionality. Do not use this tag for
          portability of performance enhancements and adaptations.
    tags: changelog

  - name: fix
    desc: Patches or quick-repair jobs designed to resolve build or run
          issues, inconsistent functional behavious, improve or correct
          security vulnerabilities, and more generally resolve bugs. New
          features _must not_ be flagges as fixes.
    tags: changelog

  - name: perf*ormance
    desc: Code rewrite to improve the performance, globally or locally
          of the software under scrutiny. Performance improvements can
          be achieved in a variety of ways, the most common being
          reducing filesystem I/O and memory consumption, or by reducing
          dependencies on third party binaries or libraries.
    tags: changelog four-eyes

  - name: port*ability
    desc: Adapting the software build to a specific operating
          environment should be flagged as a _portability_ fix. Though
          this can sometimes be tedios to track, it is a recommended
          practice to easily collect over time a body of knowledge that
          pertains to specific environments (AIX, Linux, MacOS, ...).
    tags: changelog four-eyes

  - name: proof*ing
    desc: Commits which focus on reviewing the code and proof-reading
          its documentation, to correct typos, reformulate long
          sentences, add links, etc. Developers are often tempted to
          flag such commits as _fixes_; we want to clearly distinguish
          proofing from other fixes because we don't want to keep track
          of proofing in changelogs.

  - name: refactor
    desc: Code rewrite to improve non-functional criteria (design,
          structure, implementation, ...) while preserving its
          functionality. The main purpose of this entry is to help
          discover and fix hidden or dormant bugs and vulnerabilities;
          often through code simplification. Do not use this for
          performance refactoring (see `performance` keyword). Likewise
          do not use this keyword for automated refactoring -- use the
          `batch` keyword for this.
    tags: changelog four-eyes

  - name: trans*lation
    desc: Commits that relate to language translations and other
          national language settings. We want to clearly distinguish
          such commits in that they often have a dedicated translation
          community and associated workflows. Note that adding support
          for a new language should be flagged as a _feature_, and not
          as a _translation_.

tags:

  - name: four-eyes
    desc: Commits flagged with the _four-eyes_ tag require validation by
          at least two persons.

  - name: changelog
    desc: Commits tagged with this tag will be used to assemble
          changelog views.