Contributing

Contributing to the OWLNext project

Here are some ways you can contribute:

• Participate in the forums.
• Help us improve the information on this wiki.
• Submit feature requests, bug reports and patches to the trackers.
• Review our code and documentation.

If you want to participate as an OWLNext developer or administrator with elevated access rights to the project site, then contact the current administrators by posting in the forum, at the bottom of this page or by email.

• Contributing to the OWLNext project
  • Guidelines for contributors
  • Administering the OWLNext project site
    • Tools
      • SSH
      • SFTP
      • RSync
    • Updating the online documentation
    • Code repository backup
    • References
  • Preparing and releasing a new version

---

Guidelines for contributors

Contributors should follow these guidelines:

• Submitting bugs and feature requests; our guidelines for the tracker fields and contents.
• Coding Standards; our standards for patches and revisions to the OWLNext source code.
• Doxygen documentation guidelines; how to document the OWLNext API.

Here are some advice and prerequisites to get started:

• Get to know the code repository layout and the Subversion (SVN) version control system. The TortoiseSVN client for Windows is highly recommended and has good documentation.
• Make sure you thoroughly read the guidelines above. Look at the code log to get a feel for our style.
• Learn to use the issue trackers (Bugs and Feature Requests).
• Review and contribute to our Roadmap.
• Review and contribute to the documentation in our wiki.

---

Administering the OWLNext project site

The following sections contain some notes on project site management. The command line examples assume that your user name is "admin". Replace "admin" with your real user name. To get administrator privileges, contact the current administrators or SourceForge.

Tools

Various free command line tools are useful for working with the project site. The following examples are based on a Linux setup. If you work on Windows, you can e.g. use a virtual machine with Linux to use these tools. Another option is to use a GNU-style shell, such as Cygwin, or the Bash shell in Windows 10.

SSH

The SourceForge shell server lets you work on the project site for a limited amount of time (4 hours). The following command connects to SourceForge SSH shell server:

$ ssh -t admin,owlnext@shell.sourceforge.net create

SFTP

The following command is fine for doing single file (e.g. large zipped archive) transfer to and from the project web space:

$ sftp admin,owlnext@web.sourceforge.net

RSync

RSync works with SSH internally to provide secure, powerful and simple file transfer and synchronisation of file systems across the public network. For example, to copy the project website:

$ rsync -e "ssh -l admin" admin,owlnext@web.sourceforge.net:/home/project-web/owlnext/htdocs .

Updating the online documentation

RSync is well suited for updating the Online OWLNext Documentation. Assuming that you have the updated documentation files in the local folder "documentation/html", this command updates the online documentation:

$ rsync -avsz --delete --chmod=D755,F644 -e "ssh -l admin" documentation/html admin,owlnext@web.sourceforge.net:/home/project-web/owlnext/htdocs/help/.

The --chmod option makes sure that directories will have full permissions (read, write and execute) for "admin", while only read and execute (browse) permissions for the group and others, and that files will have read and write permissions for "admin", but only read permission for the group and others. For the other options used here, see the rsync documentation.

Code repository backup

Create and log into an SSH shell. Change the current directory to the code repository, and issue the "svnadmin dump" command. For example:

$ cd /home/svn/p/owlnext/code
$ svnadmin dump . > backup.dump

Then copy the dump file to your preferred backup destination. For example, use RSync from a local console:

$ rsync -e "ssh -l admin" admin,owlnext@shell.sourceforge.net:/home/svn/p/owlnext/code/backup.dump .

References

• https://www.software.ac.uk/guide/how-create-and-manage-sourceforge-projects

---

Preparing and releasing a new version

This section describes the administrative steps you need to perform to prepare and release a new version of OWLNext.

1. Unless the new version is a minor ABI-compatible update, create a new release branch in the code repository (i.e. create a copy in "branches/. (sourceforge.net)").
    
2. Update the version number in "source/owlcore/version.h" on the release branch, and set the OWL_PRERELEASE flag to 1.
    
3. If applicable, update OWLMaker to recognise the new version and the supported compilers.
    
4. Create new version milestones in the Bugs and Feature Requests tracker tools.
    
5. Create and/or target tickets for the version milestones.
    
6. Review the resolutions to the tickets.
    
7. Release:
    
   1. Do a full build test of all libraries and configurations, ideally with all supported compilers. Make sure OWL_BUILD_DIRTY == 0 in "include/owl/version.h", i.e. that you have no uncommitted changes in the source code. Make sure you test that the documentation builds without errors as well. Ideally, also run test cases ("examples/classes", in particular) to make sure changed parts work as intended and that there are no regressions.
       
   2. Unless the release is an unfinished developer preview (also known as an "alpha" or "beta" pre-release), set the OWL_PRERELEASE flag in "source/owlcore/version.h" to 0.
       
   3. Tag the state of the release branch in the code repository (i.e. create a copy in "tags", which can be done by using the Tortoise SVN Branch/Tag command in the root for the branch that is tagged and choosing "/tags/{version tag}" as the destination). See existing tags for the naming convention. Don't forget to specify a commit message ("Created tag for {version number}.").
       
   4. Close the relevant tickets and milestones.
       
   5. Rebuild the documentation and upload an updated help file (CHM) to "Files/documentation". Before you build the documentation, make sure that build setup has been done, so that "include/owl/version.h" exists, and check that OWL_BUILD_DIRTY == 0 (no uncommitted changes). Unless the release is for an older version, update the online documentation as well (see section "Updating the online documentation" earlier on this page).
       
   6. Upload a snapshot of the updated version of the source code to "Files/source". See existing archives for the correct directory structure.
       
   7. If OWLMaker has changed, upload the updated version to "Files/tools". See the existing archive for the correct contents and directory structure. Ideally, you should digitally sign the executables in the archive (otherwise virus checkers, browsers and operating systems may deem them unsafe). This requires that you have access to a trusted code signing certificate, or that a trusted third-party entity (e.g. a trusted project member) can sign the executables for you. Also make sure that the archive passes virus checking (e.g. at VirusTotal).
       
   8. Update the version numbers in "Files/files-readme.md (sourceforge.net)" (OWLMaker parses this file to check for updates).
       
   9. Document the release in the wiki page "OWLNext Releases". If relevant, update wiki pages "Installing OWLNext", "Supported Compilers", "Upgrading from OWL" (section "Changes in OWLNext"), "FAQ", as well as any other wiki page affected by the changes.
       
   10. Create a News post announcing the release.