search

OpenWaterAnalytics / EPANET

The Water Distribution System Hydraulic and Water Quality Analysis Toolkit
MIT License
281 stars 205 forks source link

Re-write of main Readme.md #538

Closed LRossman closed 5 years ago

LRossman commented 5 years ago

I think everyone agrees that the Readme text on the project's main page needs some fixing. I've taken a shot at revising it as shown below. Let's discuss.

OWA-EPANET

Build Status

Build status Build Status

codecov

INTRODUCTION

EPANET is an industry-standard program for modeling the hydraulic and water quality behavior of water distribution system pipe networks. The EPANET Programmer's Toolkit is a library of functions (or API) written in C that allow programmers to customize the use of EPANET's solution engine for their own applications. Both EPANET and its toolkit were originally developed by the U.S. Environmental Protection Agency (USEPA). If you are interested in using/extending the EPANET engine and its API for academic, personal, or commercial use, then you've come to the right place.

CONTRIBUTING

Everyone is welcome to submit Issues and contribute code to this project. To contribute, first comment on an outstanding Issue, then Fork this repo to your own account and base your commits on the dev branch. Once you are finished, you can open a Pull Request to test the code and discuss merging your changes back into the community repository. A step-by-step tutorial on how to contribute to OWA-EPANET using GitHub is also available.

BUILDING

Instructions for building the OWA-EPANET Toolkit's function library as well as its command line executable from the source files in this repository can be found here.

DOCUMENTATION

Full documentation on how to use OWA-EPANET along with complete descriptions of its library functions can be found here (add link to where the Doxygen-generated HTML files are stored on GitHub). Additional information may be found on this project's Wiki.

DISCLAIMER

This repository is not affiliated with, or endorsed by, the USEPA. For the last "official" release of EPANET (2.00.12 UI and Toolkit) please go to the EPA's GitHub repo or the USEPA website. It is also not the graphical user interface version. This is the hydraulic and water quality solver engine.

For more general community discussion, FAQ, and roadmapping of the project, please go to the Community Forum.

eladsal commented 5 years ago

In the introduction, maybe we ought to add to "Both EPANET and its toolkit were originally developed by the U.S. Environmental Protection Agency (USEPA)." that now it is further developed by the community.

samhatchett commented 5 years ago

this is fantastic - thanks @LRossman

I might suggest something like the following to the Contributing portion to cover more than just code-contributors and help it feel as welcoming as possible. We can also use a special CONTRIBUTING.md file which will be offered to new visitors by the GH website to help familiarize them.

Everyone is welcome to participate in this project. Whether you are helping others to resolve issues, reporting a new issue that hasn't yet been discovered, suggesting a new feature that would benefit your workflow, or writing code (or tests, or scripts, or ...), we value your time and effort. The path for contribution starts with the Issues. Look around at open Issues and the conversation around them, get engaged by commenting on an outstanding Issue or creating a new one. If you want to contribute code, it helps to give the community time to discuss the ideas you present and offer constructive feedback. Once you get a clear path forward, Fork this repo to your own account. Make your commits on your dev branch (or one based on dev). Once you are finished, you can open a Pull Request to test the code and discuss merging your changes back into the community repository. A step-by-step tutorial on how to contribute to OWA-EPANET using GitHub is also available.

eldemet commented 5 years ago

I think we are missing in the Introduction a sentence about OWA, define OWA-EPANET and how it is related to USEPA-EPANET. Perhaps something like this:

The Open Water Analytics (OWA) Community is an international group of EPANET developers and users, whose objective is to provide group interaction and coordinated development of the EPANET codebase, to ensure that important new user interface and algorithmic features are identified and that these features progress efficiently from prototype code to production implementations. OWA is actively maintaining the OWA-EPANET, a community-supported branch of USEPA EPANET, since May 2014.

samhatchett commented 5 years ago

Suggest we move this discussion to PR #539 - I've incorporated the comments so far into that PR.