kicad-doc/docs-versioning.adoc

Docs Versioning
===============

This document is a work in progress and improvement suggestions are
welcome.

The purpose of this document is to specify how the given version for a
document relates to the official releases of the main KiCad software
itself. The audience of this manuscript is documentation writers and
packagers. This also means that discussion about this topic does
usually not belong on the KiCad developers list, but rather on the
kicad-doc repository on github.

== Main KiCad

The versioning of the main KiCad application is made with a triplet,
starting from 4.0.0. From the documentation teams point of view we
would like to make it easy for everyone to deduce which documentation
document that is applicable to whatever KiCad version of interest the
end use might have. Therefore the docs are versioned to match the
KiCad releases but appended with a new tuple.

== KiCad Documentation

This new tuple appended to the KiCad version triplet will be an
incrementing integer which is incremented whenever the documentation
writers are ready to call a snapshot in the git tree ready for
consumption.

Because the KiCad documentation is translated to multiple
internationalized languages there are multiple triggers for a new
"snapshot" of the documentation state, in the sense a single edition
of a translated version calls for a new version for all the docs. This
means that we release the documentation as a monolithic release, or in
other words a snapshot of all languages, determined by git tags.

== Tagging and Branching Strategy

Every release of the documentation is composed of the git tree using
the tags assigned on the given branch, usually the master branch.

If, for some reason, there are going to be backported changes to some
old release triplet (read KiCad aligned documentation version), then
this can branch out, but will be a dead end which should never be
intended to be merged back into master. It is up to the document
writers to make sure that useful additions to a backport are applied
on master if they are still relevant.

A single tag does not denote a release, because a release consists of
different time states of the repository. This is because this enables
the translations not to break whenever the English documentation is
updated, but the translators are not quick enough to follow along.

The purpose of all this version joggling is because we want the
documentation releases to be updated independent of the KiCad release
cycle, but still align with it, at the same time making it easy for
the documentation maintainers call for a new release.

== Branch Relations, Working Rules for Document

KiCad application is developed on *lp:kicad* development branch,
and new functions for the future release are developed here.
On the other hand, stable version of KiCad is maintained on stable
branch (e.g. *lp:kicad/4.0*), and bugfix version of stable KiCad
releases will come out from here.

Having separate branches for devs and maintenance enables 2 different jobs
independent.
To follow this way of management, docs team also uses multi branches.

The *master* branch is for docs development and relates to *lp:kicad* KiCad
application development branch.
We will update original English docs here.
Docs stable branch (e.g. *4.0*) is for translation and relates to
stable KiCad application branch (e.g. *lp:kicad/4.0*).
We will manage localized stable docs here.

```
[[Application - launchpad]]
<lp:kicad>     [+]--------------------[+]  -  -  -  - {development}
                |                      |
                V                      V
<stable>       [#]------$-----        [#]  -  -  -  - {bugfix, maintenance}
               <lp:kicad/4.0>

[[Documentation - GitHub]]
<master>       [+]--------------------[+]  -  -  -  - {writers}
                |                      |
                V                      V
<stable>       [#]------$-----        [#]  -  -  -  - {translators}
               <4.0>    4.0.3         <5.0>
```

On *master* branch:

- Writers update English .adoc files and related English menu screenshots.
- Translators have to understand that the master reference documents
  (English .adoc) are volatile here, so translations will probably be
  invalidated quickly. We don't reject translation works here, but would
  recommend to post to stable branch.

On stable branch (e.g. *4.0*):

- Translators create Localized .po files and related localized menu screenshots
  for stable docs.
- In case if you want to modify original English .adoc files here for fixing
  typo or something, be careful not to invalidate the translations by it.
  Usually, it is resolved by also fixing the english typo in the `msgid` of all
  po files.

Branching stable from *master*:

- Stable docs branch is made from *master* branch when the English docs
  for the next application release are ready.
- Old stable docs branches remain as historical branch.

== Packaging

This convoluted release tagging process needs to be supported by the
cmake scripts, such that it is easy for packagers to package the docs
in the way they want it.

I propose that we make cmake be able to generate a release tarball
where it only includes the relevant versions of the files that is
needed to generate the documentation output.

== Useful hints for translators

The documentation branching sometimes creates more work of what it should
necessary to translators. Please consult the
https://github.com/KiCad/kicad-doc/blob/master/translation_instructions.adoc[translators
guide] for a hint on some tools that should make life easier to
translators.