vcs.rst

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
-----------

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.