Need contribution guide

[samhatchett]

Should have a section in README about the GitHub Flow model and specific guidelines about how collaboration, branching, and PRs work for this project. Anybody want to volunteer some language?

[LRossman]

@samhatchett I wonder if you should hold off on posting any guidelines until after the WDSA conference, on the chance that the Open Source project committee might want to develop their own guidelines. In retrospect, I wonder if we jumped the gun a bit by making epanet-dev public and declaring it a part of the Open Source project without getting any sign off from the committee.

That said, I see no issue with drafting a set of guidelines, that would also include some coding standards and conventions, that could be posted at a later date when we feel we have a green light to do so. I also suggest having just a link in the README to detailed guidelines posted in the docs folder, so as not to clutter up README with a lot of details (I thought it was supposed to be just a project overview).

[jamesuber]

This is really not an issue Lew. One of the things we have continually discussed in the "steering" committee meetings (that Sam is part of) is that our role is mainly to, somehow, help get development going. We do not have anything at all to say about development or coding guidelines as that needs to be left to those actively developing the code.

You and Sam and all the others who are actually developing need to make these decisions. As others want to join and engage, they will start by contributing issues and bug fixes and code.

In summary, this is working. You all should be encouraged and appreciated. Let's not F it up by overthinking the hierarchy.

Jim

Jim Uber • 513-368-6303 • www.citilogics.com

On Jul 23, 2016, at 8:37 AM, Lew Rossman [email protected] wrote:

@samhatchett I wonder if you should hold off on posting any guidelines until after the WDSA conference, on the chance that the Open Source project committee might want to develop their own guidelines. In retrospect, I wonder if we jumped the gun a bit by making epanet-dev public and declaring it a part of the Open Source project without getting any sign off from the committee.

That said, I see no issue with drafting a set of guidelines, that would also include some coding standards and conventions, that could be posted at a later date when we feel we have a green light to do so. I also suggest having just a link in the README to detailed guidelines posted in the docs folder, so as not to clutter up README with a lot of details (I thought it was supposed to be just a project overview).

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[samhatchett]

Everyone from the development committee is watching the repo and getting these updates, so i don't see a reason to wait on this. We won't even all be at the conference so this is where we have to make these decisions. And we are in agreement that this is a reasonable starting point for a project. please correct me if I'm wrong in any of this @eladsal @eldemet

Good thoughts @LRossman on including coding conventions and formatting standards. Any existing references or tools that we can just appropriate? I've used clang-format previously and have been impressed.

I think the main emphasis was to get some basic info together about how OSS collaboration takes place in the general sense, and also a description of how to use the tools: committing, branching, squash-merging, etc. I've just been getting some questions about using the tools and how to get started contributing, and I hoped to rough-in something prior to WDSA creating more traffic here.

some main points to consider for inclusion:

• commits and PRs should be in response to an Issue or Milestone (provides opportunity for discussion prior to lots of work being done).
• PRs must be "landed" or sponsored by a Collaborator (someone with commit permission to this repo)
• description of semantic versioning convention and how it relates to which branches are used for development, hot fixes, and features.

[eldemet]

@samhatchett yes that's true. In any case we need to establish some basic instructions on how to use Github, because we cannot assume that all researchers working with EPANET have expertise in this type of open collaboration.

What's more, these instructions could also serve as a framework of good practice for all the researchers in our field who are jumping into open-source, or wish to share their codes.

[goanpeca]

Hi all, on Spyder, we have a small guide on the wiki for the workflow with github, it can basically be adapted by changing a couple of lines and would offer a starting point.

https://github.com/spyder-ide/spyder/wiki/Dev%3A-Github-Workflow

Github Wiki is a good place to store all this info regarding coding styles, best practices, do's and dont's.

An additional option for providing guide to new contributors is to include a README.md on every folder that gives explanations on the specifics of that folder/module. This is rendered on github so it is a very friendly and gentle way of introducing potential users that are exploring the codebase on github.

Also in general is cleaner to always use the fork model (even for maintainers and core developers) and to always use PRs.