From a32b92ba473ba04030fb8b851ef29704a793898a Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Fri, 2 Jun 2017 15:12:09 +0200 Subject: [PATCH] Add profiling and release information for developers --- doc/source/develop/index.rst | 4 +++- doc/source/develop/profiling/index.rst | 13 +++++++++++++ doc/source/develop/profiling/install.rst | 25 +++++++++++++++++++++++++ doc/source/develop/profiling/qcachegrind.png | Bin 0 -> 699576 bytes doc/source/develop/profiling/usage.rst | 32 ++++++++++++++++++++++++++++++++ doc/source/develop/releasing/create.rst | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/develop/releasing/index.rst | 14 ++++++++++++++ doc/source/develop/releasing/merge.rst | 4 ++++ doc/source/develop/releasing/pipeline.rst | 6 ++++++ doc/source/develop/releasing/tag.rst | 4 ++++ 10 files changed, 222 insertions(+), 1 deletion(-) create mode 100644 doc/source/develop/profiling/index.rst create mode 100644 doc/source/develop/profiling/install.rst create mode 100644 doc/source/develop/profiling/qcachegrind.png create mode 100644 doc/source/develop/profiling/usage.rst create mode 100644 doc/source/develop/releasing/create.rst create mode 100644 doc/source/develop/releasing/index.rst create mode 100644 doc/source/develop/releasing/merge.rst create mode 100644 doc/source/develop/releasing/pipeline.rst create mode 100644 doc/source/develop/releasing/tag.rst diff --git a/doc/source/develop/index.rst b/doc/source/develop/index.rst index 50f68bd..becc863 100644 --- a/doc/source/develop/index.rst +++ b/doc/source/develop/index.rst @@ -29,13 +29,15 @@ You are highly invited to join one of the next coding sprints. You can also follow `@ctools_software `_ on twitter to get informed about new ctools releases. -Below a few links to learn how to contribute to ctools: +Below some reasources to learn how to contribute to ctools: .. toctree:: :maxdepth: 1 git/index coding/index + profiling/index + releasing/index And here some status shields: diff --git a/doc/source/develop/profiling/index.rst b/doc/source/develop/profiling/index.rst new file mode 100644 index 0000000..c92389b --- /dev/null +++ b/doc/source/develop/profiling/index.rst @@ -0,0 +1,13 @@ +.. _dev_profiling: + +Profiling ctools +================ + +Profiling of the ctools can be done by various tools. Here we describe how ctools can be +profiled using valgrind. + +.. toctree:: + :maxdepth: 2 + + install + usage diff --git a/doc/source/develop/profiling/install.rst b/doc/source/develop/profiling/install.rst new file mode 100644 index 0000000..5b0a58a --- /dev/null +++ b/doc/source/develop/profiling/install.rst @@ -0,0 +1,25 @@ +.. _dev_profiling_install: + +Installing valgrind +=================== + +Mac OS X +-------- + +The tools necessary to profile ctools on Mac OS X are best installed using +Homebrew. Below the sequence of things that need to be installed: + +.. code-block:: bash + + $ brew install qcachegrind + $ brew install valgrind + $ brew install GraphViz + +Now you should have ``qcachegrind`` and ``valgrind`` installed: + +.. code-block:: bash + + $ which qcachegrind + /usr/local/bin/qcachegrind + $ which valgrind + /usr/local/bin/valgrind diff --git a/doc/source/develop/profiling/qcachegrind.png b/doc/source/develop/profiling/qcachegrind.png new file mode 100644 index 0000000..b083ed0 Binary files /dev/null and b/doc/source/develop/profiling/qcachegrind.png differ diff --git a/doc/source/develop/profiling/usage.rst b/doc/source/develop/profiling/usage.rst new file mode 100644 index 0000000..aa044b6 --- /dev/null +++ b/doc/source/develop/profiling/usage.rst @@ -0,0 +1,32 @@ +.. _dev_profiling_usage: + +Using valgrind +============== + +Mac OS X +-------- + +A valgrind analysis is performed using the ``valgrind`` executable. Here we +show as example how the :ref:`ctobssim` tool is profiled. The ``valgrind`` +executable should be run in a specific repository since a large number of +output files will be generated by the tool. + +.. code-block:: bash + + $ valgrind --tool=callgrind -v --dump-every-bb=10000000 ctobssim ra=83.63 dec=22.01 rad=5.0 tmin=0.0 tmax=1800.0 emin=0.1 emax=100.0 caldb=prod2 irf=South_0.5h inmodel=$CTOOLS/share/models/crab.xml outevents=events.fits + +While the ``valgrind`` executable is still running you can start already the +``qcachegrind`` executable that will display the analysis results: + +.. code-block:: bash + + $ qcachegrind + +This will open up a window with the profiling results displayed in tabular and +graphical form. An example of the window is shown in the figure below: + +.. figure:: qcachegrind.png + :width: 600px + :align: center + + *qcachegrind window* diff --git a/doc/source/develop/releasing/create.rst b/doc/source/develop/releasing/create.rst new file mode 100644 index 0000000..f54e914 --- /dev/null +++ b/doc/source/develop/releasing/create.rst @@ -0,0 +1,121 @@ +.. _dev_releasing_create: + +Create the release +================== + +The ctools release is created by invoking the release manager: + +.. code-block:: bash + + $ dev/release.py + ctools release manager + ====================== + + [1] Make a new release + [2] Set the package version in current branch + [3] Set the libtool version in current branch + [4] Commit changes in current branch + [5] Create tarball from current branch + [6] Check tarball + [q] Quit + Enter your choice: + +To create a new release type ``1``. You will then be guided through a number +of questions. In the example below we show how you go from the development +version ``1.2.0.dev1`` to the release ``1.2.0``. The first step is to create +a ``release`` branch. + +.. code-block:: bash + + Make a new release + ------------------ + Step 1: Do you want to create a 'release' branch? (y/n): y + Created new branch 'release' + Switched to a new branch 'release' + +Then you have to set the version number of the release. + +.. code-block:: bash + + Step 2: Current ctools version is '1.2.0.dev1'. Do you want to change the package version? (y/n): y + Current ctools version is '1.2.0.dev1'. Please enter new ctools version: 1.2.0 + Change version to '1.2.0'? (y/n): y + ctools version changed to '1.2.0' + +After this the libtool version number will be set. **The libtool version number +will in general be different from the release version number.** The new libtool +version number is determined from the source code and interface changes with +respect to the last release. You therefore have to answer a couple of +questions about the changes you did. + +.. code-block:: bash + + Step 3: Current Libtool version is '2:0:0'. Do you want to change the libtool version? (y/n): y + Current libtool version is '2:0:0'. Do you want to change the version? (y/n): y + Has the source code changed since last release? (y/n): y + Have interfaces been added since last release? (y/n): y + Have interfaces been removed since last release? (y/n): y + Have interfaces changed since last release? (y/n): y + Libtool version changed to '3:0:0' + +Then you have to commit all changes and push then into the git repository. + +.. code-block:: bash + + Step 4: Commit changes? (y/n): y + The following files have been changed: + M README.md + M configure.ac + M ctools.pc.in + M doc/Doxyfile + M doc/source/conf.py + M sonar-project.properties + Commit all changes? (y/n): y + [release 6d01085] ctools package version set to '1.2.0' and libtool version set to '3:0:0' + 6 files changed, 9 insertions(+), 9 deletions(-) + + Step 5: Push changes? (y/n): y + Counting objects: 10, done. + Delta compression using up to 8 threads. + Compressing objects: 100% (10/10), done. + Writing objects: 100% (10/10), 809 bytes | 0 bytes/s, done. + Total 10 (delta 8), reused 0 (delta 0) + remote: To https://github.com/ctools/ctools.git + remote: * [new branch] release -> release + To https://cta-gitlab.irap.omp.eu/ctools/ctools.git + * [new branch] release -> release + +You then should build and check the source tarball to verify that everything +went fine. Note that this step is not formally needed for a release since +the software release will start from the code in the ``release`` branch. + +.. code-block:: bash + + Step 6: Build tarball? (y/n): y + Log actions in logfile? (y/n): y + Configure package + Package configuration successful + Create tarball + Tarball creation successful + + Step 7: Check tarball? (y/n): y + Log check in logfile? (y/n): y + Configure package + Package configuration successful + Check tarball + Tarball checking successful + +Now you are done and can quite the release manager. + +.. code-block:: bash + + [1] Make a new release + [2] Set the package version in current branch + [3] Set the libtool version in current branch + [4] Commit changes in current branch + [5] Create tarball from current branch + [6] Check tarball + [q] Quit + Enter your choice: q + + diff --git a/doc/source/develop/releasing/index.rst b/doc/source/develop/releasing/index.rst new file mode 100644 index 0000000..ecaed2f --- /dev/null +++ b/doc/source/develop/releasing/index.rst @@ -0,0 +1,14 @@ +.. _dev_releasing: + +Creating a new ctools release +============================= + +To create a new ctools release you have to go through the following steps: + +.. toctree:: + :maxdepth: 2 + + create + pipeline + tag + merge diff --git a/doc/source/develop/releasing/merge.rst b/doc/source/develop/releasing/merge.rst new file mode 100644 index 0000000..24d89f8 --- /dev/null +++ b/doc/source/develop/releasing/merge.rst @@ -0,0 +1,4 @@ +.. _dev_releasing_merge: + +Merge release branch into master branch +======================================= diff --git a/doc/source/develop/releasing/pipeline.rst b/doc/source/develop/releasing/pipeline.rst new file mode 100644 index 0000000..e852ff4 --- /dev/null +++ b/doc/source/develop/releasing/pipeline.rst @@ -0,0 +1,6 @@ +.. _dev_releasing_pipeline: + +Launch the release pipeline +=========================== + + diff --git a/doc/source/develop/releasing/tag.rst b/doc/source/develop/releasing/tag.rst new file mode 100644 index 0000000..7acd8d9 --- /dev/null +++ b/doc/source/develop/releasing/tag.rst @@ -0,0 +1,4 @@ +.. _dev_releasing_tag: + +Tag the release +=============== -- libgit2 0.21.4