Version Control
===============

A functional quality software needs a version control system,
which provides several advantages.

    1. Record versions
        so that you can rollback the software to any history version.
    2. Collaboration between developers
        so that multiple developers can work simultaneously to enhance efficiency.
    3. Keep multiple braches
        so that software can be developed in a separate branch
        and it does not affect the stable (released) version.
    4. Code safety
        the approve-merge mechanism, etc.

``git``
-------
``git`` is probably the most widely used version control system presently.

    - official website: https://git-scm.com/
    - **Pro Git** (2nd Ed.): https://git-scm.com/book/en/v2


Basic usages
------------
To initialize a repository:

.. code-block:: bash

    git init

To add a remote source

.. code-block:: bash

    git remote add origin https://csst-tb.bao.ac.cn/code/csst-l1/csst_proto.git

To show a remote source `origin`

.. code-block:: bash

    git remote show origin

To clone a remote repository

.. code-block:: bash

    git clone https://csst-tb.bao.ac.cn/code/csst-l1/csst_proto.git

To pull remote code to local

.. code-block:: bash

    git pull origin main

To view the git log

.. code-block:: bash

    git log

To view the current status

.. code-block:: bash

    git status

To add your revisions to version control

.. code-block:: bash

    git add ./test.py

To make a commit

.. code-block:: bash

    git commit -m "make a test commit"

To push to remote repository

.. code-block:: bash

    git push origin main

To reset repository to a specific commit

.. code-block:: bash

    git reset 82cc809698b3b52327a0360eea10b88aacbadec6 --hard

To configure your git

.. code-block:: bash

    git config --global user.name "Your Name"
    git config --global user.email "your_email@address"

You can also store your credentials on disk via

.. code-block:: bash

    git config --global credential.helper store


.. note::

    Please DO NOT use command ``git add .`` which makes the Version Control system
    track all files in the repository -- It may include many useless files such as
    ``*.py~`` (temporary files generated by text editor).


Work flow with ``git``
----------------------
In CSST DAS pipeline development, each developer registers an account at the
`CSST DAS GitLab`_, which is a self self-managed `GitLab`_ instance
to host data processing pipelines at NAOC.
More specifically, the L1 Pipelines are developed in the `csst-l1`_ group.

Developers are required to upload their code to the repository.
The repository should have three branches:

- ``main`` branch: for a stable version
- ``dev`` branch: for development
- ``release`` branch: for code release

After the pipeline is integrated (probably the end of C6),
a code reviewer is required to merge approved code revisions into ``main`` branch.


.. _CSST DAS GitLab: https://csst-tb.bao.ac.cn/code
.. _GitLab: https://about.gitlab.com/
.. _csst-l1: https://csst-tb.bao.ac.cn/code/csst-l1


Code review mechanism
---------------------

Starting from C7, developers of all packages should NOT directly push any code
to *main* branch which is protected.
A reviewer is needed to approve the committed modifications before
merging into the *main* branch.

Developers should switch to a ``dev`` branch before doing anything.
Then commit code and push them to ``dev`` branch.


Workflow with ``dev`` branch
----------------------------

.. code-block::
    :caption: As a developer:

    (base) cham@MBP16 csst_proto % git branch -a # show all branch
      dev
    * main
      remotes/origin/main
    (base) cham@MBP16 csst_proto % git checkout dev # check out dev -> then you are in dev branch
    M       doc/source/conf.py
    M       doc/source/index.rst
    M       doc/source/integration.rst
    M       doc/source/vcs.rst
    Switched to branch 'dev'
    (base) cham@MBP16 csst_proto % git status # view code changes
    On branch dev
    Changes not staged for commit:
      (use "git add <file>..." to update what will be committed)
      (use "git restore <file>..." to discard changes in working directory)
            modified:   doc/source/conf.py
            modified:   doc/source/index.rst
            modified:   doc/source/integration.rst
            modified:   doc/source/vcs.rst

    Untracked files:
      (use "git add <file>..." to include in what will be committed)
            doc/contents.md

    no changes added to commit (use "git add" and/or "git commit -a")
    (base) cham@MBP16 csst_proto % git add doc/source/*.rst doc/source/conf.py # add your code changes
    (base) cham@MBP16 csst_proto % git commit -m "updated doc: author info and docker info" # commit your changes
    [dev bbed3fa] updated doc: author info and docker info
     4 files changed, 73 insertions(+), 4 deletions(-)
    (base) cham@MBP16 csst_proto % git push origin dev # as a developer you are not allowed to push to main branch
    Enumerating objects: 15, done.
    Counting objects: 100% (15/15), done.
    Delta compression using up to 10 threads
    Compressing objects: 100% (8/8), done.
    Writing objects: 100% (8/8), 1.67 KiB | 1.67 MiB/s, done.
    Total 8 (delta 6), reused 0 (delta 0), pack-reused 0
    remote:
    remote: To create a merge request for dev, visit:
    remote:   http://10.3.10.28/code/csst-l1/csst_proto/-/merge_requests/new?merge_request%5Bsource_branch%5D=dev
    remote:
    To https://csst-tb.bao.ac.cn/code/csst-l1/csst_proto.git
     * [new branch]      dev -> dev

.. code-block::
    :caption: As a code reviewer:

    (base) cham@MBP16 csst_proto % git checkout main # check out main branch
    Switched to branch 'main'
    Your branch is up to date with 'origin/main'.
    (base) cham@MBP16 csst_proto % git merge dev # merge dev branch into main AFTER view changes
    Updating d9f64d3..bbed3fa
    Fast-forward
     doc/source/conf.py         |  2 +-
     doc/source/index.rst       | 11 +++++++++++
     doc/source/integration.rst | 50 +++++++++++++++++++++++++++++++++++++++++++++++---
     doc/source/vcs.rst         | 14 ++++++++++++++
     4 files changed, 73 insertions(+), 4 deletions(-)
    (base) cham@MBP16 csst_proto % git push origin main # push to remote main branch
    Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
    To https://csst-tb.bao.ac.cn/code/csst-l1/csst_proto.git
       d9f64d3..bbed3fa  main -> main

As a developer, you can also create a merge requrest to ask code reviewers to merge your changes on GitLab.

First, click ``Merge requests`` tag, click ``
    .. image:: vcs/merge_request.png
Second, select source branch and target branch, create a new merge request.
    .. image:: vcs/create_merge_request.png
The code reviewers should then view the chagnes, and decide whether the changes should be approved.
    .. image:: vcs/create_merge_request.png
If the changes are accepted, approve and merge the changes into `main` branch.
    .. image:: vcs/merge_approve.png
After the changes have been merged, code reviewers should leave comment on the changes.
    .. image:: vcs/merged.png