From 259ecb2c0a3817c5fea9b0f0f8a26a8070a11e8f Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Wed, 7 Jun 2017 16:51:35 +0200 Subject: [PATCH] Update documentation for release 1.3 --- Makefile.am | 2 ++ doc/source/develop/profiling/index.rst | 2 +- doc/source/develop/releasing/create.rst | 2 +- doc/source/develop/releasing/devel.rst | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/develop/releasing/index.rst | 11 ++++++++++- doc/source/develop/releasing/merge.rst | 10 ++++++++++ doc/source/develop/releasing/pipeline.png | Bin 0 -> 486356 bytes doc/source/develop/releasing/pipeline.rst | 12 ++++++++++++ doc/source/develop/releasing/tag.rst | 14 ++++++++++++++ doc/source/users/release_history/1.3.rst | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/users/release_history/index.rst | 1 + doc/source/users/tutorials/1dc/first_fitting.rst | 76 ++++++++++++++++++++++++++++++++++++++-------------------------------------- 12 files changed, 235 insertions(+), 41 deletions(-) create mode 100644 doc/source/develop/releasing/devel.rst create mode 100644 doc/source/develop/releasing/pipeline.png create mode 100644 doc/source/users/release_history/1.3.rst diff --git a/Makefile.am b/Makefile.am index d1ee67f..36d0edf 100644 --- a/Makefile.am +++ b/Makefile.am @@ -58,6 +58,8 @@ uninstall-local: $(DOXYGEN_UNINSTALL_DATA_TARGETS) # Files to be removed in build directory clean-local: rm -rf $(top_builddir)/.DS_Store + rm -rf $(top_builddir)/doc/html + rm -rf $(top_builddir)/doc/man # # Additional rules diff --git a/doc/source/develop/profiling/index.rst b/doc/source/develop/profiling/index.rst index c92389b..636351f 100644 --- a/doc/source/develop/profiling/index.rst +++ b/doc/source/develop/profiling/index.rst @@ -7,7 +7,7 @@ Profiling of the ctools can be done by various tools. Here we describe how ctool profiled using valgrind. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 install usage diff --git a/doc/source/develop/releasing/create.rst b/doc/source/develop/releasing/create.rst index f54e914..592eb83 100644 --- a/doc/source/develop/releasing/create.rst +++ b/doc/source/develop/releasing/create.rst @@ -58,7 +58,7 @@ questions about the changes you did. 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. +Then you have to commit all changes and push them into the git repository. .. code-block:: bash diff --git a/doc/source/develop/releasing/devel.rst b/doc/source/develop/releasing/devel.rst new file mode 100644 index 0000000..907e670 --- /dev/null +++ b/doc/source/develop/releasing/devel.rst @@ -0,0 +1,82 @@ +.. _dev_releasing_merge: + +Incrementing the development version +==================================== + +As last step you have to increment the version number to the next +development release number. Before doing that you should make sure that you +have merged the released software version into the devel branch. You do this +by typing: + +.. code-block:: bash + + $ git checkout devel + $ git merge master + +Now you launch again the release manager to update the version number: + +.. 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: + +Select ``2`` and enter the new version number: + +.. code-block:: bash + + Current ctools version is '1.2.0'. Please enter new ctools version: 1.3.0.dev1 + Change version to '1.3.0.dev1'? (y/n): y + ctools version changed to '1.3.0.dev1' + + [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: + +Now commit the changes by chosing ``4``: + +.. code-block:: bash + + 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 + Please enter a commit message: Update to release version 1.3.0.dev1 + [devel d38bbdc] Update to release version 1.3.0.dev1 + 6 files changed, 8 insertions(+), 8 deletions(-) + + [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: + +Quit the release manager by chosing ``q`` and push the modifications into +the repository: + +.. code-block:: bash + + $ git push origin + +Congratulations, you are done! diff --git a/doc/source/develop/releasing/index.rst b/doc/source/develop/releasing/index.rst index ecaed2f..c6df712 100644 --- a/doc/source/develop/releasing/index.rst +++ b/doc/source/develop/releasing/index.rst @@ -6,9 +6,18 @@ Creating a new ctools release To create a new ctools release you have to go through the following steps: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 create pipeline tag merge + devel + +.. important:: + Before releasing the software please make sure that you have + + * added unit tests for all new code + * added a page about the software changes to the release history + * updated the User documentation if necessary + diff --git a/doc/source/develop/releasing/merge.rst b/doc/source/develop/releasing/merge.rst index 24d89f8..acea0bd 100644 --- a/doc/source/develop/releasing/merge.rst +++ b/doc/source/develop/releasing/merge.rst @@ -2,3 +2,13 @@ Merge release branch into master branch ======================================= + +The master branch should always contain the last release of the ctools +package. You therefore have to merge now the release branch into the master +branch by typing: + +.. code-block:: bash + + $ git checkout master + $ git merge release + $ git push origin diff --git a/doc/source/develop/releasing/pipeline.png b/doc/source/develop/releasing/pipeline.png new file mode 100644 index 0000000..c5875a5 Binary files /dev/null and b/doc/source/develop/releasing/pipeline.png differ diff --git a/doc/source/develop/releasing/pipeline.rst b/doc/source/develop/releasing/pipeline.rst index e852ff4..5a2faea 100644 --- a/doc/source/develop/releasing/pipeline.rst +++ b/doc/source/develop/releasing/pipeline.rst @@ -3,4 +3,16 @@ Launch the release pipeline =========================== +Now you should connect to +`Jenkins `_ +and launch the ctools release pipeline by clicking on the dedicated +button: +.. figure:: pipeline.png + :width: 600px + :align: center + + *ctools release pipeline* + +In case that any errors occur during running the release pipeline, you should +fix the errors and rerun the pipeline until it terminates with success. diff --git a/doc/source/develop/releasing/tag.rst b/doc/source/develop/releasing/tag.rst index 7acd8d9..4a2893c 100644 --- a/doc/source/develop/releasing/tag.rst +++ b/doc/source/develop/releasing/tag.rst @@ -2,3 +2,17 @@ Tag the release =============== + +Now you should tag the software with the current release number. You do this +by typing: + +.. code-block:: bash + + $ git tag -a ctools-1.2.0 -m "ctools release 1.2.0" + +You push the tag to the repository by typing: + +.. code-block:: bash + + $ git push origin --tags + diff --git a/doc/source/users/release_history/1.3.rst b/doc/source/users/release_history/1.3.rst new file mode 100644 index 0000000..a8b4001 --- /dev/null +++ b/doc/source/users/release_history/1.3.rst @@ -0,0 +1,64 @@ +.. _1.3: + +ctools 1.3 release (7 June 2017) +================================ + +Overview +-------- + +ctools 1.3 is a major release that adds significant functionality. + +In particular, this release provides: + +* :ref:`ctphase` for phasing events +* :ref:`ctprob` for event probabilities +* :ref:`csebins` for an automatic computation of an optimal energy binning + +Bug fixes +--------- + +* [`2121 `_] - + Correct covariance matrix computation in ctbutterfly +* [`2114 `_] - + Add missing ``*.i`` SWIG file into release tarball +* Use correct ROOT histograms in :ref:`csroot2caldb` +* [`1987 `_] - + Copy cscripts into bin directory instead of creating a symbolic links +* [`1983 `_] - + Raise exception instead of exiting with return code in Python tests +* Support of map cubes lying outside RoI in ctobssim +* [`1975 `_] - + Consider RoI in :ref:`ctskymap` and use numerical integration for IRF +* [`1370 `_] - + Set local language to english + + +Improvements +------------ + +* [`1996 `_] - + Add ``phase`` parameter to :ref:`ctselect` +* [`1989 `_] - + Implement regression scheme in :ref:`cssens` and remove ``num_avg`` parameter +* [`1985 `_] - + If code originates from Git, always compile the Python bindings +* [`1978 `_] - + Support energy boundary FITS file in ctmapcube +* [`1863 `_] - + :ref:`ctlike` stores covariance matrix in either CSV or FITS format +* [`1862 `_] - + Implement Gaussian error propagation in :ref:`ctbutterfly` +* [`1483 `_] - + :ref:`ctobssim` adds Monte Carlo identifiers to simulated events +* Enhance logfile output of :ref:`csroot2caldb` script +* Set default ``deadc`` value to 0.98 (CTA has <2% deadtime) + +New features +------------ + +* [`1991 `_] - + Add :ref:`ctprob` tool +* [`1982 `_] - + Add :ref:`ctphase` tool +* [`1976 `_] - + Add :ref:`csebins` script diff --git a/doc/source/users/release_history/index.rst b/doc/source/users/release_history/index.rst index 33489f2..fb04c25 100644 --- a/doc/source/users/release_history/index.rst +++ b/doc/source/users/release_history/index.rst @@ -8,6 +8,7 @@ Major releases: .. toctree:: :maxdepth: 1 + ctools 1.3 <1.3> ctools 1.2 <1.2> ctools 1.1 <1.1> ctools 1.0 <1.0> diff --git a/doc/source/users/tutorials/1dc/first_fitting.rst b/doc/source/users/tutorials/1dc/first_fitting.rst index 81e925e..6bd571b 100644 --- a/doc/source/users/tutorials/1dc/first_fitting.rst +++ b/doc/source/users/tutorials/1dc/first_fitting.rst @@ -48,44 +48,44 @@ converged properly, as illustrated in the example below: .. code-block:: bash - 2017-06-01T10:55:30: +=================================+ - 2017-06-01T10:55:30: | Maximum likelihood optimisation | - 2017-06-01T10:55:30: +=================================+ - 2017-06-01T10:55:44: >Iteration 0: -logL=242348.647, Lambda=1.0e-03 - 2017-06-01T10:55:58: >Iteration 1: -logL=222180.556, Lambda=1.0e-03, delta=20168.091, step=1.0e+00, max(|grad|)=50061.839794 [Index:13] - 2017-06-01T10:56:11: >Iteration 2: -logL=218667.504, Lambda=1.0e-04, delta=3513.051, step=1.0e+00, max(|grad|)=-11303.423190 [RA:6] - 2017-06-01T10:56:24: >Iteration 3: -logL=217668.566, Lambda=1.0e-05, delta=998.938, step=1.0e+00, max(|grad|)=-9596.810651 [RA:6] - 2017-06-01T10:56:38: >Iteration 4: -logL=217500.656, Lambda=1.0e-06, delta=167.910, step=1.0e+00, max(|grad|)=-6620.600218 [RA:6] - 2017-06-01T10:56:52: >Iteration 5: -logL=217460.888, Lambda=1.0e-07, delta=39.769, step=1.0e+00, max(|grad|)=-4306.170420 [RA:6] - 2017-06-01T10:57:05: >Iteration 6: -logL=217441.548, Lambda=1.0e-08, delta=19.339, step=1.0e+00, max(|grad|)=3170.609703 [RA:0] - 2017-06-01T10:57:20: >Iteration 7: -logL=217432.039, Lambda=1.0e-09, delta=9.510, step=1.0e+00, max(|grad|)=2239.034002 [RA:0] - 2017-06-01T10:57:34: >Iteration 8: -logL=217427.577, Lambda=1.0e-10, delta=4.461, step=1.0e+00, max(|grad|)=1582.498191 [RA:0] - 2017-06-01T10:57:48: >Iteration 9: -logL=217425.390, Lambda=1.0e-11, delta=2.188, step=1.0e+00, max(|grad|)=1162.116922 [RA:0] - 2017-06-01T10:58:03: >Iteration 10: -logL=217424.221, Lambda=1.0e-12, delta=1.169, step=1.0e+00, max(|grad|)=815.765881 [RA:0] - 2017-06-01T10:58:17: >Iteration 11: -logL=217423.683, Lambda=1.0e-13, delta=0.538, step=1.0e+00, max(|grad|)=542.812704 [RA:0] - 2017-06-01T10:58:31: >Iteration 12: -logL=217423.482, Lambda=1.0e-14, delta=0.200, step=1.0e+00, max(|grad|)=288.286783 [RA:0] - 2017-06-01T10:58:45: >Iteration 13: -logL=217423.422, Lambda=1.0e-15, delta=0.060, step=1.0e+00, max(|grad|)=221.413071 [RA:0] - 2017-06-01T10:59:00: >Iteration 14: -logL=217423.378, Lambda=1.0e-16, delta=0.044, step=1.0e+00, max(|grad|)=226.131427 [RA:0] - 2017-06-01T10:59:17: >Iteration 15: -logL=217423.330, Lambda=1.0e-17, delta=0.048, step=1.0e+00, max(|grad|)=180.270743 [RA:0] - 2017-06-01T10:59:32: >Iteration 16: -logL=217423.309, Lambda=1.0e-18, delta=0.020, step=1.0e+00, max(|grad|)=104.148460 [RA:0] - 2017-06-01T10:59:46: >Iteration 17: -logL=217423.303, Lambda=1.0e-19, delta=0.007, step=1.0e+00, max(|grad|)=63.327107 [RA:0] - 2017-06-01T11:00:00: >Iteration 18: -logL=217423.298, Lambda=1.0e-20, delta=0.004, step=1.0e+00, max(|grad|)=42.005734 [RA:0] - 2017-06-01T11:00:14: - 2017-06-01T11:00:14: +=========================================+ - 2017-06-01T11:00:14: | Maximum likelihood optimisation results | - 2017-06-01T11:00:14: +=========================================+ - 2017-06-01T11:00:14: === GOptimizerLM === - 2017-06-01T11:00:14: Optimized function value ..: 217423.298 - 2017-06-01T11:00:14: Absolute precision ........: 0.005 - 2017-06-01T11:00:14: Acceptable value decrease .: 2 - 2017-06-01T11:00:14: Optimization status .......: converged - 2017-06-01T11:00:14: Number of parameters ......: 16 - 2017-06-01T11:00:14: Number of free parameters .: 10 - 2017-06-01T11:00:14: Number of iterations ......: 18 - 2017-06-01T11:00:14: Lambda ....................: 1e-21 - 2017-06-01T11:00:14: Maximum log likelihood ....: -217423.298 - 2017-06-01T11:00:14: Observed events (Nobs) ...: 2204717.000 - 2017-06-01T11:00:14: Predicted events (Npred) ..: 2204716.997 (Nobs - Npred = 0.00283915968611836) + 2017-06-06T23:54:05: +=================================+ + 2017-06-06T23:54:05: | Maximum likelihood optimisation | + 2017-06-06T23:54:05: +=================================+ + 2017-06-06T23:54:18: >Iteration 0: -logL=242350.348, Lambda=1.0e-03 + 2017-06-06T23:54:31: >Iteration 1: -logL=222183.040, Lambda=1.0e-03, delta=20167.308, step=1.0e+00, max(|grad|)=50064.145481 [Index:13] + 2017-06-06T23:54:44: >Iteration 2: -logL=218671.485, Lambda=1.0e-04, delta=3511.555, step=1.0e+00, max(|grad|)=-11302.678938 [RA:6] + 2017-06-06T23:54:57: >Iteration 3: -logL=217673.527, Lambda=1.0e-05, delta=997.958, step=1.0e+00, max(|grad|)=-9593.644236 [RA:6] + 2017-06-06T23:55:10: >Iteration 4: -logL=217505.751, Lambda=1.0e-06, delta=167.776, step=1.0e+00, max(|grad|)=-6625.379605 [RA:6] + 2017-06-06T23:55:23: >Iteration 5: -logL=217465.972, Lambda=1.0e-07, delta=39.779, step=1.0e+00, max(|grad|)=-4315.893743 [RA:6] + 2017-06-06T23:55:37: >Iteration 6: -logL=217446.648, Lambda=1.0e-08, delta=19.324, step=1.0e+00, max(|grad|)=3158.486974 [RA:0] + 2017-06-06T23:55:50: >Iteration 7: -logL=217437.175, Lambda=1.0e-09, delta=9.473, step=1.0e+00, max(|grad|)=2234.551298 [RA:0] + 2017-06-06T23:56:03: >Iteration 8: -logL=217432.730, Lambda=1.0e-10, delta=4.445, step=1.0e+00, max(|grad|)=1578.966812 [RA:0] + 2017-06-06T23:56:17: >Iteration 9: -logL=217430.542, Lambda=1.0e-11, delta=2.187, step=1.0e+00, max(|grad|)=1164.679821 [RA:0] + 2017-06-06T23:56:31: >Iteration 10: -logL=217429.374, Lambda=1.0e-12, delta=1.168, step=1.0e+00, max(|grad|)=816.726019 [RA:0] + 2017-06-06T23:56:44: >Iteration 11: -logL=217428.835, Lambda=1.0e-13, delta=0.539, step=1.0e+00, max(|grad|)=543.038385 [RA:0] + 2017-06-06T23:56:58: >Iteration 12: -logL=217428.635, Lambda=1.0e-14, delta=0.201, step=1.0e+00, max(|grad|)=290.465021 [RA:0] + 2017-06-06T23:57:12: >Iteration 13: -logL=217428.574, Lambda=1.0e-15, delta=0.061, step=1.0e+00, max(|grad|)=223.932827 [RA:0] + 2017-06-06T23:57:25: >Iteration 14: -logL=217428.528, Lambda=1.0e-16, delta=0.046, step=1.0e+00, max(|grad|)=228.672746 [RA:0] + 2017-06-06T23:57:38: >Iteration 15: -logL=217428.480, Lambda=1.0e-17, delta=0.049, step=1.0e+00, max(|grad|)=179.805198 [RA:0] + 2017-06-06T23:57:52: >Iteration 16: -logL=217428.459, Lambda=1.0e-18, delta=0.021, step=1.0e+00, max(|grad|)=103.278218 [RA:0] + 2017-06-06T23:58:05: >Iteration 17: -logL=217428.452, Lambda=1.0e-19, delta=0.006, step=1.0e+00, max(|grad|)=62.896707 [RA:0] + 2017-06-06T23:58:18: >Iteration 18: -logL=217428.448, Lambda=1.0e-20, delta=0.004, step=1.0e+00, max(|grad|)=41.622300 [RA:0] + 2017-06-06T23:58:31: + 2017-06-06T23:58:31: +=========================================+ + 2017-06-06T23:58:31: | Maximum likelihood optimisation results | + 2017-06-06T23:58:31: +=========================================+ + 2017-06-06T23:58:31: === GOptimizerLM === + 2017-06-06T23:58:31: Optimized function value ..: 217428.448 + 2017-06-06T23:58:31: Absolute precision ........: 0.005 + 2017-06-06T23:58:31: Acceptable value decrease .: 2 + 2017-06-06T23:58:31: Optimization status .......: converged + 2017-06-06T23:58:31: Number of parameters ......: 16 + 2017-06-06T23:58:31: Number of free parameters .: 10 + 2017-06-06T23:58:31: Number of iterations ......: 18 + 2017-06-06T23:58:31: Lambda ....................: 1e-21 + 2017-06-06T23:58:31: Maximum log likelihood ....: -217428.448 + 2017-06-06T23:58:31: Observed events (Nobs) ...: 2204717.000 + 2017-06-06T23:58:31: Predicted events (Npred) ..: 2204716.997 (Nobs - Npred = 0.00284357415512204) You may also convert the fitted model positions into a `ds9 `_ region file using the :ref:`csmodelinfo` script so that you can overlay the -- libgit2 0.21.4