Community Contributions

[bemcdonnell]

@michaeltryby, I'd like to explore and strategize the best pathways forward to bring in contributions from the community into the next (or a future) release of SWMM. Do you have any initial thoughts on this?

[michaeltryby]

@bemcdonnell I have been away on vacation. Happy to discuss with you. Feel free to call my office line or drop me an email at your convenience.

[michelleannesimon]

I have edited the EPANET contributing instructions for SWMM. What do you think?

[SWMM Contributors Guide.docx]

[dickinsonre]

Or convert it to a txt file?

[michelleannesimon]

Let's try txt
SWMM Contributors Guide.txt

[michelleannesimon]

I may not have put the entire path foe the doc file. Let me know if you can read it.

[bemcdonnell]

@michelleannesimon, Thanks for sharing this document. The open source community at OWA is very excited to engage in this process!

[MitchHeineman]

Rewritten as markdown, although I suspect some of the text is outdated.

SWMM Contributors Guide

Thank you for taking the time to look through these SWMM submission guidelines and considering supporting this effort. All contributions are welcome, including bug reports, bug fixes, documentation improvements, and enhancements.

Purpose

The purpose of this guide is to orient potential contributors to the source code contribution and acceptance process for United States (U.S.) Environmental Protection Agency's (EPA's) SWMM software project. This guide briefly describes the testing framework, the copyright and license, steps in the contribution process, and answers some frequently asked questions.

Quality Assurance and Quality Control (QA/QC)

Quality assurance and quality control (QA/QC) are key to ensuring the software will run correctly. This is particularly important in an open-source environment. Code associated with new features in a contribution must include reproducible tests that verify and document that the software is working as intended. If your changes impact existing code that already has a testing component, you do not need to program a test (unless your new code is somehow causing an old test to fail—these cases will be considered individually if they occur). When merged with the current version of SWMM, contributed code must not cause regression error in features that were previously known to be working correctly. QA/QC testing must be reproducible and generate a permanent record for documentation purposes that describes the software under test, the test being run, and the result of the tests. To eliminate the burden of QA/QC related testing, EPA is pursuing a strategy of test automation utilizing Continuous Integration (CI) tools. Source code and tests from contributors should be written to integrate with the project's chosen CI toolchain (Appveyor, Travis CI, and Circle CI).

Software Copyright and Licensing

Software produced by EPA and its affiliates (i.e., any person under current contract/grant/cooperative agreement to the EPA) is considered a "written work" of the U.S. Federal Government and therefore resides in the public domain. EPA can, however, hold the copyrighted work of third parties. Third party contributors can therefore dedicate their work to the public domain, or copyright and license it. EPA will honor the license of a third-party contributor, provided it is suitable Open Source Initiative (OSI) approved open source license that does not conflict with those portions of the code base residing in the public domain or with licensed contributions made by other parties. Because SWMM has historically been released as public domain software, liberal open source (OS) licenses such as the MIT License or BSD License are preferred.

Version Control

The SWMM software projects use git distributed version control software to manage changes to the source code, developer documentation, and build configuration. GitHub is a web based platform for sharing git software repositories and the latest changes to the code with fellow developers. Git has many features that support code management in multi-developer teams. Git is powerful but can be complicated. It is well documented and many resources for learning how to use git and GitHub effectively are available online.

Prerequisites for Contributors

Groups of people with many talents working together make the best software. There are many ways to contribute to EPA's open source projects including, software development, technical writing, testing, submitting bugs, making feature requests, and helping fellow users. Because we use git and GitHub to manage software configuration and organize contributions, familiarity with these tools and the ability to effectively use them is a prerequisite to making contributions. The project wiki has git instructions for beginning contributors to make things easier.

If you are interested in contributing software, then you probably can already use git. In addition, it is useful to become familiar with the project build and configuration, developer guidelines, and software internals. You are welcome to learn all these things on your own, but it's a lot easier to learn and get things done by joining and working as part of a developer community.

Step by Step Instructions for Software Contributors

1. Join GitHub and visit the EPA GitHub site
2. Contact the maintainer of the GitHub repository and discuss the nature of contributions you have in mind.
3. If a similar issue in the GitHub repository does not already exist, create one describing your contribution and the problem it will solve or the feature it will implement. The merits of your contribution might be publicly discussed by the community.
4. Configure git and initiate work on your bug fix or feature idea in your branch GitHub repository.
5. Adhere to development guidelines and coding standards in line with community norms.
6. Commit your code frequently to your branch GitHub repository and ask for input periodically.
7. Update the community on your progress.
8. When the code is ready, issue a pull request in git to the master GitHub repository. By submitting a pull request, you make an agreement with EPA that you will not submit a claim of compensation for services rendered to EPA or any other federal agency. Further, you agree not to charge the time you spend developing software code related to this project to any federal grant or cooperative agreement.
9. Your contribution will be reviewed by the maintainer of the master GitHub repository prior to acceptance.
10. Address reviewer comments.
11. Maintainer might merge your pull request or provide feedback on how it can be improved.

Documentation and User Manual Updates

Updates to developer documentation and software User's Manuals must accompany source code contributions to explain what it does, how it interacts with other components, what it needs to function appropriate, and what it returns—as applicable. If the goal of a change is to fix a bug, the bug number should also be included in the code to help identify where those errors were. Documentation updates are required for approval. We are in the process of selecting tools and converting formats to better support community contributions to documentation.

Criteria for Acceptance

• Does the contribution address a publicly posted known issue within the repository?
• Is your feature discussed in the project development roadmap?
• What are the merits of the contribution?
• Does the code adhere to development and code style guidelines adopted by the community?
• Does the contribution adhere to quality assurance guidelines?
• Is the contribution properly documented?
• Does the contribution present a user training or support issue?

Frequently Asked Questions

How can I become a contributor?

Many opportunities exist for the community to become involved and contribute to the open source development of SWMM. The best way to become a contributor is to become active on the GitHub repository. You don't need to know anyone to get started.

• If you are a SWMM user and have a great idea for a new feature, share it as a feature request on the GitHub website.
• If you are an experienced user without knowledge of how to program, you can contribute to the open source community by providing help with documentation.
• If you want to gain some programming experience, you could provide help with testing.
• If you know how to develop software and want to learn more about SWMM, you could provide fixes for bugs documented in the Issue tracker on the GitHub repository.
• If you are a modeling expert with software development experience, you can contribute a new feature.

Which repo should I contribute to?

Although the SWMM repositories at US EPA's Enterprise Site can and will accept pull requests from individuals wishing to support this effort, we encourage individual developers to submit pull requests to one of the community-based repositories supporting this effort. In this way, the enterprise repository will house the source code and supporting files for major versions. While community-based groups will contain active forums, bug reporting, and more frequent development activity. Major versions from the community groups will be submitted to this repository once they confirm with community contribution guidelines and are approved. The primary development activity for SWMM is occurring as part of the Open Water Analytics community development group. This repository points to a community forum and a bug reporting page that is actively monitored by a community looking to improve and expand SWMM.

Why is git so complicated?

Git is a distributed version control system that EPA has adopted for source code and software configuration management. It is powerful, but new users can find it complicated. Many online resources are available to help learn effective git usage. The GitHub help pages are a great resource for learning Git.

Is there a peer review process for contributions?

Peer review is required for pull requests and is an important element of EPA project's quality control strategy. EPA has found through experience that peer review of contributions can be stressful for some contributing developers. EPA strives to maintain a professional peer review process and enforce a code of conduct within the development community to head off problems.

What about quality assurance and documentation?

Developed and maintained by EPA, SWMM is a commercial quality software. Rigorous QA/QC and full documentation are hallmarks of commercial-quality software. Therefore, QA/QC, testing, and documentation are essential aspects of the contributor process for SWMM. Contributors are expected to demonstrate the quality of their contribution and fully document in order for the contribution to be included in an official SWMM release. Software development is a process, development, testing, and documentation can occur in parallel over time while the maintainer works with the contributor on their contribution. When the contribution is accepted and ready (i.e., fully tested and documented), it is eligible to be scheduled for inclusion in an upcoming SWMM release.

Why isn't my contribution being accepted?

EPA is interested in open source development and community contributions to SWMM, but it is important to realize that contributions will not be automatically accepted. The EPA project officer reserves the final right to reject contributions from the official versions of SWMM. EPA will adhere to criteria of acceptance guidelines and be transparent in the decision-making process.

Contact Information

If you have any additional questions, please contact [email protected].

[bemcdonnell]

@MitchHeineman, this is a trivial detail but worth stating here. When Michelle drafted that the link was broken to the former “OWA” SWMM. That new link (and working) is:

https://github.com/pyswmm/Stormwater-Management-Model

Lots of good stuff going on over there :-)

[MitchHeineman]

I revised the text accordingly, although various other revisions are needed as Caleb noted.

[cbuahin]

Some of the text is definitely outdated. The language about code ownership and licensing and the QA requirements will likely need to be tightened.

[cbuahin]

This the language that has been used by other projects within the agency regarding pull requests.

By submitting a pull request, you make an agreement with EPA that you will not submit a claim of compensation for services rendered to EPA or any other federal agency. Further, you agree not to charge the time you spend developing software code related to this project to any federal grant or cooperative agreement.

[MitchHeineman]

I added that to the "Step by Step Instructions for Software Contributors" section

[cbuahin]

It will make sense for folks to fork the SWMM repo to their personal accounts and do their work there. Once they are done, they can make a pull request to the official USEPA SWMM repo.