[ostorybook-dev] [GIT] proposal

[Bruno Raoult <braoult@xxxxxx>]

Hi,


Please find below a draft for a document about GIT usage, as discussed 
on the forum.

If accepted on the principle, I will include it somewhere in "doc" GIT 
directory.
Again, it is just a draft, giving hints only, and you could consider it 
is completely useless, in which case I will not pollute GIT :-)

TODO: add some git commands/examples to explain the different steps.

br.

----------------------------------------------------
*** DRAFT *** GIT workflow *** DRAFT***

CURRENT SITUATION

Our current git workflow is the following:
- Master is the development branch, and is therefore not considered as 
"stable"
- There are neither branches, nor tags.
- The only "pseudo-branches" are the local copies of master on developer
  machines.

This can be represented as:


Dev 1 local --- dev---------------------etc..
           /          \        \
          /pull        \merge   \merge
         /              \        \
Master--------------------R1--R1------R2------------------
          \         /          /     \        /
           \pull   /merge     /merge  \pull  /merge
            \     /          /         \    /
Dev 2 local  --- dev------------------------ etc...

The releases R1 and R2 are simply a snapshot (but untagged) of the 
development
(master) branch, used to build the different OSes packages.
In fact, there is no way of finding back any released version (so that an
archive of source files is also generated together with packages).
You will notice the 2 "R1" releases. This happens currently when some 
bugs are
found in a release: a quick fix is made, and the "same" R1 is released 
(meaning
that different users with "same" R1 release have in fact 2 different 
versions,
as we can see on the user forum.
It should be emphasized that what differentiates versions is (and is only) a
string manually managed in 2 places source code.

POSSIBLE IMPROVEMENTS ON RELEASE NAMING

Without changing current workflow, we could imagine two ways (between 
others)
to have better version numbers:

1) Any Rx release could be unique (i.e. we cannot have 5.00.02 twice with
different source code), and any Rx is a GIT tag. Many possibilities here:
 - We keep current naming and add some information (4th number, or 
timestamp):
   5.00.02-01, 5.00.02-02, etc...
   or:
   5.00.02-20170130-15:32, etc.
 - We change current version numbering, the second number being the 
release,
   and the third number a patch number:
   5.02.01, 5.02.03, etc...

2) To avoid source code change for versioning, we could use ant/git to:
 - have the version directly included in build.xml (given that the 
developer
   has the "git" command)
 - generate automatically a "version.java", which would contain only the
   specific build version information (version, maybe a few others: date,
   person making the build, etc...).
   A few different possibilities here (given we use only ant), one of them
   being: We could use a "template" source, and use the ant "replace" 
function
   to replace some tags (for instance: @@GIT-VERSION@@, @@BUILD-DATE@@, 
etc...).

Advantages:
 - We would know exactly which version a user is using, and, more 
important, we
   could easily "git checkout" the same version, to reproduce the issue 
with
   the exact same build.
 - The version number would be in only one place (the GIT tag)
 - No manual change in source code and build.xml

Drawbacks:
 - The version number is highly "static" and manually managed (as GIT 
tags are).

POSSIBLE IMPROVEMENTS ON WORKFLOW (REPOSITORY SIDE)

Dev 1 local --- dev---------------------etc..
           /          \        \
          /pull        \merge   \merge
         /              \        \
Master--------------------R1--R1------R2------------------
            \           \       /      /        /
             \branch R1  \     /merge /merge   /merge
              \           \   /      /        /
R1 branch      --- bug fixes ------------------(EOL)
                            \               /
                             \branch R2    /
                              \           /
R2 branch                      -- bug fixes ------- (EOL)

In this workflow, we keep the same master branch for development, and each
release is a branch.
Not much difference with the tag-based versions, except that it is easier to
switch to a given branch.

What is important to note is that each developer has a full copy of the git
tree (then all branches). This makes the switch to a branch much easier 
than in
a pure tag-based versioning.

Tags could still be used for build numbers or other information.

POSSIBLE IMPROVEMENTS ON WORKFLOW (DEVELOPER SIDE)

We could imagine that developers *always* work on a temporary branch, on 
their
side.
This means:
- everytime we work on a bug fix, we create a branch such as "favdb - R2 
- bug
  FS50"  or "jean - R2 - PDF export crash".
- everytime we work on an improvement, we create a branch such as "favdb -
  import/export XML"

More: For huge/long developments, developers could create as many 
sub-branches
as they want (such as "favdb - import XML", "favdb - export XML"), to 
ease the
testing, these sub-branches being merged to the developer's own branch from
time to time.
Of course, branches purpose is to help, no to disturb. A developer will 
do what
he prefers (or not) for sub-branches.

However, having always a new branch for any bug fix/any new feature, helps a
lot to track back the issues: Git offers some tools (git-blame, etc...) 
to try
to find where a problem could come from (author/branch).
No specific branch implies only commits are given by git-blame, so that 
it is
difficult/impossible to know if it was a bug fix or a specific project.




--
oStorybook dev team