Developer guidelines
This set of guidelines is intended for O2scl developers.
Release procedure
- Make sure version numbers are updated in configure.ac, doc/o2scl/doxyfile, doc/o2scl/main.dox, snap/snapcraft.yaml, and tables in dl_page.dox are updated with "not yet set" for the new version hashes.
- For most recent commit, make sure the tests, examples, and documentation all succeed. Check source installs on ubuntu and OS X and a homebrew HEAD install.
- Try a test build on travis-ci.org
- Make sure snaps are working using
sudo snapcraft -d cleanbuild
- Update NEWS file with recent changes.
- Make the final commit targeted for release.
- Check the commit succeeds on travis-ci.org
- Promote the snaps on snapcraft from edge to beta at https://snapcraft.io/o2scl/releases .
- Refresh the documentation using
make o2scl-doc
.
- Create the new distribution and copy to internal svn repo.
- Create github release, tagging the recent commit and uploading the distribution.
- Compute hashes with
md5sum
and openssl dgst -sha256
and update dl_page.dox with hashes and github release hash. Regenerate documentation with make o2scl-doc
.
- Do a 'make install' on isospin so that 'make utk-sync-doc' can copy docs from the post-installation directory
- Copy the new distribution and the new sha256 hash to https://isospin.roam.utk.edu/public_data/o2scl_dists/
- Update homebrew recipe with the new version number and new hash.
- Check installation using homebrew directly.
- Turn on build pushes in travis-ci.org and commit again since dl_page.dox has changed.
Procedure for moving to new development version:
- Update to the new development version number and new OLIB numbers in configure.ac .
- Update version numbers in doxyfile files and main.dox files and in dl_page.dox .
- Update local configure scripts to refer to new version number if necessary
o2sclpy release procedure:
- Update version numbers in o2sclpy/__init.py, doc/conf.py, setup.py, snap/snapcraft.yaml and doc/index.rst
- Regenerate the o2sclpy documentation using
make doc
and upload it to web using make sync-doc
- Remove old dists in o2sclpy by clearing o2sclpy/dist directory
- Run
python3 setup.py sdist bdist_wheel
- Upload a new version of o2sclpy to pypi using
twine upload dist/*
Coding recommendations and guidelines:
Documentation guidelines:
- Refer to other classes with \ref if necessary. Refer to function parameters with \c or embed them in html TT (text-type) commands.
- Bibliographic references should be used. When possible, include the DOI link which begins with the prefix http://dx.doi.org (not the vendor-specific DOI link).
- Comment Doxygen documentation with \comment and \endcomment. (Yes, sometimes comments in comments are useful.)
git repository:
- Communicate with the lead developer before, during, and after any non-trivial development. Communicate your ideas before development, so that you don't write many lines of code only to find that your pull request will be rejected. Communicate your ideas during development to avoid conflicting changes. Communicate your ideas after development to ensure they have a chance of being implmented. Subversion is not a replacement for real communication.
- Pull requests will be integrated into the trunk by the lead developer at whatever time they deem appropriate.
- Developer-specific files which are not platform-independent should not be added to the repository. Sometimes
.gitignore
can be used to ignore these files, but this should be done sparingly.