Contributing new programs to Madagascar

If you want to share your code with other Madagascar users:

1. Follow the guide on Adding new programs to Madagascar.
2. If your employer holds the copyright for your software, obtain permission to distribute under a GPL license and place a copyright and GPL license notice in each file with code.
3. Sign up at GitHub.
4. Upload your directory to the Github repository by making a pull request.
5. Announce your changes in the release notes for the upcoming stable version ($RSFSRC/NEWS.txt)
6. Make sure to add reproducible examples of using your program under the $RSFSRC/book tree. Create new directories if necessary and commit them to the repository. As a rule, the release version does not include programs without examples.

Some additional helpful information is included below.

Repository procedure suggestions

Please try to do atomic commits. For coding style suggestions, please see the "Adding new programs" section.

Backward compatibility features

If you introduce or notice a feature that is used solely for backward compatibility with an old version of a dependency, please document it here so that the feature can be eliminated when the Madagascar community stops supporting that version of that dependency.

Mitigating missing dependencies

The main idea is to attempt to provide graceful degradation when facing a missing dependency. Quoting the Wikipedia page on fault-tolerant systems, this "enables a system to continue operating properly in the event of the failure of (or one or more faults within) some of its components. If its operating quality decreases at all, the decrease is proportional to the severity of the failure, as compared to a naively-designed system in which even a small failure can cause total breakdown."

Reasons for the existence of certain features

Why pyc files are generated during the install step

Python bytecode files, with the pyc extensions, are created during the scons install to:

• Register them in SCons' dependency tree so that scons remove them -c install
• Avoid a situation where a user tries to execute a Madagascar Python program but creates the pyc file during a module import fails because of lack of write access to $RSFROOT/lib.

cfortran.h

This source code file provides a machine-independent interface between C procedures, Fortran procedures, and global data (more details on the website of its initial author). It is a dependency of the F77 and F90 APIs, as well as of vplot. It is included in m8r in api/f90 with a link in api/f77. Version 4.3 (2002) is still distributed through the original author's website. Another version (fork?) is maintained at CERN and distributed in the include directory of the interface to event generators in the Monte Carlo libraries in the CERN Program Library (CERNlib). Debian distributes the Free Software part of this package as cernlib. Under Fedora, cfortran.h is included in cernlib-g77-devel and cernlib-devel, which happily overwrite each other's files and create copies of cfortran.h in two different locations deeply nested under /usr/include. CERNlib's Debian maintainer states that "CERNlib is an ancient mass of mostly Fortran code" and that "Most components of CERNLIB are completely broken on modern 64-bit architectures", so m8r developers should be aware that CERNlib will probably be superseded in the future by ROOT, with upstream cfortran.h maintenance possibly continuing this way.

Static code checks

Madagascar contains the beginning of an implementation of static code checks for security vulnerabilities and coding mistakes with Splint. This is visible in the code through the presence of comments like /*@out@*/ and /*@null@*/, which instruct Splint about the intent of different variables and function return values. Plans include dynamic checking by Valgrind or IBM's Rational Purify. Madagascar code metrics are assessed periodically by Open Hub.

Maintaining the maintenance tools

Please document scripts that maintain the Madagascar codebase and save them in $RSFSRC/admin. Cleanup procedures may need to be repeated in the future, as authors are human and can make the same mistakes again.

Information flow map

The vector graphics original of this map in Dia format is available upon request through the rsf-devel mailing list.

Dual licensing Madagascar code

In a contractual work relationship, you may find it handy to reuse some of your existing public code for which you own the copyright. This may also apply if you are doing contract work for a client on behalf of your employer, who owns the copyright.

If your code does not have any GPL-ed dependencies, and the copyright owner agrees to release the code under a different license than the GPL, then you are free to go ahead and do it. However, make sure that in every file you state the following:

• who is the copyright owner,
• what are the terms of the proprietary license that it is being released under,
• that the code has already been licensed to the public under the GNU GPL before this as part of the Madagascar package

It is important to specify all these items, lest years later, someone in your client's company finds the code, realizes that similar code is part of Madagascar, and wrongly believes that the copyright belonged to his company and that you infringed it by releasing the code under the GPL.

Ensure that proper copyright and licensing statements are in place in case of dual licensing, even if you are on excellent terms with your client and are confident they will not falsely accuse you of wrongdoing. Companies get acquired, employees and even owners leave companies, policies and business strategies change, and old contracts, licenses, and legal documents get discarded or lost in a mass of old junk. Each source code file should contain all the relevant copyright and licensing information.