IEDA Software Sharing Policies
This policy pertains to software developed with funding provided to the Interdisciplinary Earth Data Alliance (IEDA) for which the source code is intended to be made public.
It is the intention of the IEDA management to make source code for outward facing applications developed by the alliance accessible in public repositories. This policy is intended to foster collaboration with other informatics groups, facilitate reuse, and invite review and comment by interested parties to improve the quality of our software.
In general, IEDA endorses the ESIP software guidelines, based on the current draft 2016-07-22. These guidelines are still under review at ESIP and might be superseded; discussion and revisions should be accessible via http://roomthily.github.io/technology-evaluation-research/. The IEDA guidelines will be updated if necessary based on any revisions. We also endorse the software evaluation procedures described by the Software Sustainability Institute. We aspire to follow those guidelines, but recognize that there are many legacy situations for which significant re-engineering would be required to rigorously follow the guidlines; until resources are available for major software development, IEDA will continue with currently deployed software, aligning with the guidelines to the degree possible.
In most cases, a single configuration file is used to access this information by any software in the repository. Recommended practice for public repositories is that this configuration file should contain dummy information and provide a template. When a user checks out a repository, they create a local copy of this dummy configuration file with the working access information required, and (most important!) configure their version control software so that this file is not synchronized to other repositories. For example, in git-based repositories, this is done by including the updated configuration file in the .gitignore list.
IEDA public repositories MUST NOT contain any software released with license restrictions that prevent distribution.
Each reposistory must contain a license statement that applies to all content of the repository unless other license provisions are applied in a subdirectory or an individual file.
Unless otherwise required, IEDA repositories SHALL apply the Apache 2.0 license (https://www.apache.org/licenses/LICENSE-2.0.html).
For IEDA purposes, the license applied to sofware should:
These conditions are aligned with the Apache License 2.0, Which is permissive with respect to linking other software, distribution, modification, private use, and sub licensing.
The Apache License requires preservation of the copyright notice and disclaimer, and allows use of the software for any purpose; licensees may distribute, modify, and distribute modified versions of the software under the terms of the license, without concern for royalties. Used by DataOne, TetherlessWorld, NCEAS, GeoBlacklight.
More restrictive copyleft type licenses (GNU GPL types or CC BY-SA) are not recommended because they restrict reuse by federal partners. Restriction to non-commercial use is also considered unnecessary, as we are not producing software for profit, and any reuse is considered beneficial. See Comparison of Licenses, Discussion of ‘copyleft’. An IEDA repository might include copies of software that carry such licenses, and will follow the provisions of those licenses if the source code needs to be modified for IEDA purposes.
The purpose of providing documentation for IEDA created or maintained software is to enable new team members to more readily understand how an application works when they are assigned tasks to fix bugs, upgrade, or reuse the software, especially in situations where the original developer is no longer on the team.
In some cases, software released in a public repository might become the target of a community development effort, in which case additional documentation is warranted to help outside contributors understand the goals and architecture of an application, as well as the organization of the code base, and any policies for submitting contributions and their review.
A third purpose of software and repository documentation is for transportability of IEDA capabilities in the case that operation of the data systems is transferred to a new operator. Our observation of such transitions for other data systems is that the process is normally one of extracting the information content from existing databases and repositories and transferring it to a new environment that utilizes existing software in that environment. I such a transition, very little of the data management software developed and used by IEDA is expected to be reused. Rather, the functionality of the software needs to be documented to clarify the curation and management processes and help new data managers better understand the provenance of the information resources.
An individual repository might contain many small files, and it is not practical to go back and add header information if it is not there already. In these situations, the information MUST at least be provided at the level of individual folders/directories in the repository, using a plain text readme file. Whenever practical, each source code file should include the required information in a header file.
Most documentation should be in the code-- use meaningful variable and function names. Add comments where things are not clear. For instance if you’re debugging or editing and have to think for a minute to remember what is going on somewhere, add a comment there. Each file containing code should include a header (content enumerated above).
For text file documents, versioning is important. Assign a new version number (which is given with a stable versioning strategy) at each update. Use a version tracking table describing changes and who made them at each update.
Approval for public release of software: The implementation managers for any affected software, and the Associated Director for Technology and Architecture must review the content of any repository that is to be made public to determine compatibility with the guidelines set for here.