Confluence Retirement

Due to the feedback from stakeholders and our commitment to not adversely impact USGS science activities that Confluence supports, we are extending the migration deadline to January 2023.

In an effort to consolidate USGS hosted Wikis, myUSGS’ Confluence service is targeted for retirement. The official USGS Wiki and collaboration space is now SharePoint. Please migrate existing spaces and content to the SharePoint platform and remove it from Confluence at your earliest convenience. If you need any additional information or have any concerns about this change, please contact myusgs@usgs.gov. Thank you for your prompt attention to this matter.
Skip to end of metadata
Go to start of metadata

Sent by Eric Martinez, January 31, 2018

Hello,

You are receiving this message because you are listed as the maintainer for the software project hosted at REPOSITORY_URL. If you are not the maintainer for this project, please simply respond to this email identifying the current project maintainer. If you are the project maintainer, this email will provide some potentially valuable resources as well as explain some very simple required and recommended actions for you to take in order to normalize your project with current USGS guidance.

As you may know, software development and release standards are rapidly evolving within the USGS. While official policy will eventually be available on the USGS Fundamental Science Practices [1] web site, developing standards and guidance are in progress in the USGS Best Practices [2] repository; specifically in the "software" [3] section. If you are interested in becoming a part of this conversation, you can do so in a variety of ways (in no particular order):


While much of the official policy is still in flux, there are a few administrative points that are currently well-accepted and can begin being implemented for existing source code repositories. While software may be hosted on commercial services (such as GitHub), official versions of the software must also be maintained on official government infrastructure. Since your project is hosted in the USGS Organization on GitHub [8], this step will be handled on your behalf by an automated process which will mirror your repository from GitHub back to https://code.usgs.gov/ [9]. The process of setting up this automated mirror is currently underway and no action is required by you on this point.

Software should be licensed, disclaimed, and include appropriate metadata. In addition, it is currently recommended you maintain reasonable documentation, establish contributing guidelines and a code of conduct for your repository. I've included some guidance and boiler plate attachments to make this as simple a process as possible.

Required Actions

Software should be licensed. To do this, include a "LICENSE.md" file in the root of your repository. This file should be all upper-case "LICENSE" and include a lower-case ".md" extension. An example LICENSE.md file is provided as an attachment to this email.  Most generally, software developed by or for the federal government exists in the Public Domain, however it is also acceptable to apply the Creative Commons "CC0-1.0 Universal[10] for international applicability. Licensing can become a murky subject if the repository includes dependencies licensed under different terms such as MIT, GPL, etc... If you have questions on this topic, please do not hesitate to ask.

Software should be disclaimed. To do this, include a "DISCLAIMER.md" file in the root of your repository. This file should be all upper-case "DISCLAIMER" and include a lower-case ".md" extension. Example DISCLAIMER.md file are provided as attachments to this email. The proper disclaimer to use depends on the current review and approval status of the software project. Please see the "Guidance on Disclaimer Statements Allowed in USGS Science Information Products[11] for more details.

Software should include appropriate metadata. To do this, include a "code.json" file in the root of your repository. This file should be all lower-case "code" and include a lower-case ".json" extension. A template code.json file is provided as an attachment to this email (be sure to update this if you choose to use it). For more information regarding the code.json options, please see the "metadata[12] section of the USGS Best practices repository and/or the general documentation on the code.gov website [13].

Recommended Actions

Maintain reasonable documentation. To do this, include a "README.md" file in the root of your repository. This file should be all upper-case "README" and include a lower-case ".md" extension. The README.md file should contain the project name, description, and maintainer information. It may also include getting started instructions, how to build or use the software etc... If the documentation is extensive, the README.md file might simply contain links to the more thorough documentation.

Establish contributing guidelines. To do this, include a "CONTRIBUTING.md" file in the root of your repository. This file should be all upper-case "CONTRIBUTING" and include a lower-case ".md" extension. An example CONTRIBUTING.md file is provided as an attachment to this email (be sure to update this if you choose to use it). More information on setting guidelines for repository contributors [14] can be found on the GitHub documentation pages. As part of this you may also consider adding an issue template [15] and/or pull request template [16].

Establish a code of conduct. To do this, include a "CODE_OF_CONDUCT.md" file in the root of your repository. This file should be all upper-case "CODE_OF_CONDUCT" with underscores separating each word and include a lower-case ".md" extension. An example CODE_OF_CONDUCT.md file is provided as an attachment to this email. More information on adding a code of conduct to your project [17] can be found on the GitHub documentation pages.

Regards,

Eric Martinez
U.S. Geological Survey
emartinez@usgs.gov

Attachments

Links

[1]: https://www2.usgs.gov/fsp/default.asp
[2]: https://github.com/usgs/best-practices/
[3]: https://usgs.github.io/best-practices/software/
[4]: https://github.com/usgs/best-practices/issues
[5]: mailto:gs_github@usgs.gov
[6]: https://usgs.slack.com/messages/C5PFHSBSQ/
[7]: https://my.usgs.gov/confluence/display/cdi/Software+Development+Cluster
[8]: https://github.com/usgs/
[9]: https://code.usgs.gov/

[10]: https://creativecommons.org/publicdomain/zero/1.0/legalcode

[11]: https://www2.usgs.gov/fsp/fsp_disclaimers.asp

[12]: https://github.com/usgs/best-practices/blob/master/software/metadata.md

[13]: https://code.gov/#/policy-guide/docs/compliance/inventory-code

[14]: https://help.github.com/articles/setting-guidelines-for-repository-contributors/

[15]: https://help.github.com/articles/creating-an-issue-template-for-your-repository/
[16]: https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/
[17]: https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/

  • No labels