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, 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.
- Make sure pushes are being installed on travis-ci.org
- Update NEWS file with recent changes.
- Make the final commit targeted for release. Double check that it succeeds on travis-ci.org.
- 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 and update dl_page.dox wish hashes and github release hash.
- Update internal svn web file storing sha256 hash.
- Regenerate documentation and copy dl_page.html to internal svn repo.
- Run "make utk-sync-doc" in doc/o2scl in order to move new docs to the internal svn repo.
- Go to the internal web page copy and run "make puto" to publish web docs, new distribution, and new sha256 hash.
- Update homebrew recipe.
- Check installation using homebrew directly.
- Turn on build pushes in travis-ci.org and commit again since dl_page.dox has changed.
General coding 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.)
Patches:
- For those who are uncomfortable with Subversion, patches are always accepted.
- Prepare patches based on the most recent version of the trunk or the appropriate branch.
SVN:
- Editing the trunk directly should be avoided. Most development should occur on branches, to be merged with the trunk at the appropriate time.
- Ideally the trunk should always compile and all the tests should pass.
- 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 new code 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.
- Commit often.
- Merge carefully. If you fail to merge correctly, code added by other developers will be (at least temporarily) lost.
- Branches will be merged 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 svn:ignore can be used to ignore these files, but this should be done sparingly.