#+TITLE: README for developers
#+LANGUAGE:  en
#+OPTIONS: H:3 num:t \n:nil @:t ::t |:t _:nil ^:nil -:t f:t *:t <:t
#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil pri:nil tags:not-in-toc html-style:nil

This page is dedicated to rules and conventions that Chameleon's
developers must follow and that should be read by contributors.

* Gitlab flow: how to contribute to Chameleon

  Please read and follow guidelines given in the [[file:CONTRIBUTING.org][CONTRIBUTING file]].

** Update submodules

   Chameleon git project depends on a "submodule" git, located in
   cmake_modules/morse_cmake and hosted here
   https://gitlab.inria.fr/solverstack/morse_cmake.

   To update this submodule to the last development state, follow
   these steps:

   #+begin_src sh
   git submodule update --remote cmake_modules/morse_cmake
   git commit cmake_modules/morse_cmake -m "update morse_cmake submodule"
   git push --recurse-submodules=check
   #+end_src

* Documentation
  <<sec:doc>>
** Generate the documentation
*** Prerequisites

     To generate the documentation you need to have [[http://www.stack.nl/~dimitri/doxygen/][Doxygen]] and
     [[https://orgmode.org/][org-mode]] installed on your system.

     For example, on Debian systems:
     #+begin_src sh
     sudo apt install doxygen org-mode texlive texlive-latex-extra emacs
     #+end_src

*** configure + make documentation

    Enter into the Chameleon's source root directory and configure
    with *CHAMELEON_ENABLE_DOC=ON*, then generate the documentation
    with ~make doc~

    #+begin_src sh
    cd chameleon
    mkdir build && cd build
    cmake .. -DCHAMELEON_ENABLE_DOC=ON
    make doc
    #+end_src

** Rules about source code documentation

   Please refer to this file for the documentation guidelines [[file:doc/doxygen/README.org][README]].

* Naming and writting conventions

  Chameleon library started as an extension of the PLASMA library so
  that code naming and writting conventions should follow [[https://bitbucket.org/icl/plasma][PLASMA]] ones.

* Releasing

   A Chameleon's release is a source package, of the form
   chameleon-major.minor.patch.tar.gz, which:
   1) has been properly tested,
   2) has an up-to-date ChangeLog file,
   3) is published on internet as a GitLab release plus an associated
      git tag.

** Test Chameleon before packaging

   TODO - Write the way we could systematically test Chameleon before
   packaging, for example writting a script (generated from this
   org-mode file) to be used on PlaFRIM plus some specific ctest
   tests.

** Release generation and publication

   Releases are published on GitLab automatically through the gitlab-ci
   job /release/.

   To create a release the workflow is:
   1) ensure chameleon is ready for this release, /i.e./
      - all required features are well integrated
      - all tests succeed
      - the ChangeLog file is up-to-date
      - the version number is up-to-date in all source files
   2) create and push a branch /release-major.minor.patch/,
      major.minor.patch being the version number for the release
   3) the gitlab-ci job should produce a new release and tag according
      to the version number
      - releases: https://gitlab.inria.fr/solverstack/chameleon/releases
      - tags: https://gitlab.inria.fr/solverstack/chameleon/tags
   4) delete the branch

* CDash tests dashboard
  To see details about the tests performed during the [[https://gitlab.inria.fr/solverstack/chameleon/pipelines][pipelines]] visit
  [[https://my.cdash.org/index.php?project=Chameleon][CDash]].

* Static and dynamic analysis
  To see details about the analysis job performed during the
  [[https://gitlab.inria.fr/solverstack/chameleon/pipelines][pipelines]] visit [[https://sonarqube.bordeaux.inria.fr/sonarqube/dashboard?id=hiepacs%3Achameleon%3Agitlab%3Asolverstack%3Amaster][Sonarqube]].
