SAGA Source Code Contribution

Anonymous

SAGA Committer Guidelines - Proposal

  • Use a consistent coding style, please take the module library "Lectures - Introducing Module Programming" as an example.

  • Take the time to add comments throughout your code explaining what the code is doing. It will save a huge amount of time and frustration for other programmers that may have to change your code in the future.

  • Take the time to add references (e.g. to papers) and a meaningful description to the "Module Description" section of each new module you contribute. This will allow SAGA users to get a better idea of what a module is designed for and will reduce the traffic on the user forum.

  • Use doxygen style for source code documentation, this will ensure that the automatically generated (API) reference will include these comments.

  • Existing code should not be re-indented except in extreme cases, as this will make "diff" comparisons with older versions impossible. If indent is needed, do not check in any changes other than the indentation in the same commit.

  • All source code in cvs should be in Unix text format as opposed to DOS text mode.

  • Please ensure your code is not only running in SAGA GUI, but also with SAGA CMD. There are cases a module may only be designed to work within the GUI (e.g. interactive modules).

  • When committing new features or significant changes to existing source code, the committer should take reasonable measures to ensure that the source code continues to build and work on the most commonly supported platforms (currently Linux and Windows), either by testing on those platforms directly or by getting help from other developers working on those platforms.

  • If new files or library dependencies are added, then the files configure.in, Makefile.am, makefile.linux, makefile.mingw, the MSWVC project files .dsw, .sln, .dsp, vcproj, and related documentations should be kept up to date.

  • Tell the other developers about new code or changes by providing reasonable cvs commit messages when checking in the source code. Any check-in without useful comments will be reverted because the cvs ChangeLog? is the only way for others to keep track of changes.

  • Significant changes to the main development version should be discussed on the Developer Forum hosted at sourceforge. This is especially true for those changes that break backward compatibility, e.g. changes in module parameters (naming, new parameters).

  • Significant changes accepted should be checked in with a meaningful description AND added to the compatibility.txt file. (comment: this is a file which we will need to create; this will allow easier tracking of significant changes for developers of applications building on top of SAGA or administrators of batch scripts. An example would be the RSAGA interface)

  • Those providing code to be included in the repository must understand that the code will be released under the GPL / LGPL license, and that the person providing the code has the right to contribute the code under these licenses. For the committer themselves understanding about the license is hopefully clear. For other contributors, the committer should verify the understanding unless the committer is very comfortable that the contributor understands the license (for instance frequent contributors).

  • If the contribution was developed on behalf of an employer (on work time, as part of a work project, etc) then it is important that an appropriate representative of the employer understands that the code will be contributed under the GPL / LGPL license. The arrangement should be cleared with an authorized supervisor/manager, etc.

  • The code should be developed by the contributor, or the code should be from a source which can be rightfully contributed as it is from an open source project under a compatible license.

  • Code coming from a source other than the contributor (such as adapted from another project) should be clearly marked as to the original source, copyright holders, license terms and so forth. This information should be in the file headers.

  • Existing copyright headers and license text should never be stripped from a file. If a copyright holder wishes to give up copyright they must do so in writing to the developer team before copyright messages are removed. If license terms are changed it has to be by agreement (written in email is ok) of the copyright holders.

  • In case of questions feel free to contact the developers on the Developer Forum hosted at sourceforge.


Related

Wiki: Home