Add contributing guide

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,84 @@
+
+<!--
+IMPORTANT NOTES
+
+Is this pull request ready to be merged?
+- Do the existing tests pass and new tests added for new code?
+- Is all development in a state where you are proud to share it with others and
+  willing to ask other people to take the time to review it?
+- Is it documented in such a way that a review can reasonably understand what you've
+  done and why you've done it? Can other users understand how to use your changes?
+If not but opening the pull request will facilitate development, make it a "draft" pull request.
+
+This form is written in GitHub's Markdown format. For a reference on this type
+of syntax, see GitHub's documentation:
+https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
+
+This template contains guidance for your submission within the < ! - -, - - > blocks.
+These are comments in HTML syntax and will not appear in the submission.
+Be sure to use the "Preview" feature on GitHub to ensure your submission is formatted as intended.
+
+When including code snippets, please paste the text itself and wrap the code block with
+ticks (see the other character on the tilde ~ key in a US keyboard) to format it as code.
+For example, Python code should be wrapped in ticks like this:
+```python
+def a_func():
+    return 1
+
+a = 1
+b = a_func()
+print(a + b)
+```
+This is preferred over screen shots since it is searchable and others can copy/paste
+the text to run it.
+
+YAML is also supported:
+```yaml
+a_key: a_value
+list_key:
+- item1
+- item2
+```
+-->
+
+
+# Add meaningful title here
+<!--
+Be sure to title your pull request so that readers can scan through the list of PR's and understand
+what this one involves. It should be a few well selected words to get the point across. If you have
+a hard time choosing a brief title, consider splitting the pull request into multiple pull requests.
+Keep in mind that the title will be automatically included in the release notes.
+-->
+Describe your feature here.
+
+## Related issue
+<!--
+If one exists, link to a related GitHub Issue. If one doesn't exist but should, please create it.
+Otherwise, delete this section.
+-->
+
+## Impacted areas of the software
+<!--
+List other areas that should be impacted by this pull request.
+This helps to determine the verification tests.
+-->
+
+## Additional supporting information
+<!--
+Add any other context about the code contribution here.
+-->
+
+## Test results, if applicable
+<!--
+Add the results from unit tests and regression tests here along with justification for any failing test cases.
+-->
+
+<!--
+__ For maintainer use __
+Release checklist:
+- Update the version in
+    - [ ] README.md
+    - [ ] setup.py
+- [ ] Verify docs builds correctly
+- [ ] Create a tag in the IEAWindTask37/windIO repository
+-->

docs/index.rst

@@ -19,6 +19,7 @@ The frameworks are implemented in two yaml-schemas, one for the turbine and one
 
    source/turbine
    source/plant
+   source/developer_guide
 
 
 Indices and tables

docs/source/developer_guide.rst

@@ -0,0 +1,200 @@
+Contributing Guide
+==================
+windIO was started under IEA Wind Task 37 and has been additionally supported by IEA Wind Task 55
+as well as other community-based groups, research organization, and private companies.
+Being a collaborative effort, it is important to establish a common understanding of the
+rules, responsibilities, and expectations from all stakeholders.
+**This document outlines the processes and guidelines for contributing to windIO.**
+
+The windIO repository includes JSON schemas, YAML and NetCDF files that describe examples
+of wind energy systems conforming to the schemas, Python code for working with the schemas
+and input files, source files for web-based documentation,
+and various other files that serve as infrastructure.
+Changes to anything that is tracked with git in the windIO repository is considered a contribution,
+and these guidelines apply.
+
+
+Code of Conduct
+~~~~~~~~~~~~~~~
+As members of the wind energy community, we all agree that the advancement of wind
+energy technologies is critical for the sustainability of our planet.
+This shared goal should be reflected in our interactions with each other.
+Remember that we're all on the same team despite differences in our day to day stressors and needs.
+
+Two principles should guide our conduct:
+
+- `Think that you might be wrong. <https://en.wikipedia.org/wiki/Cromwell%27s_rule>`_
+- `Assume good faith. <https://en.wikipedia.org/wiki/Wikipedia:Assume_good_faith>`_
+
+
+Contribution management
+~~~~~~~~~~~~~~~~~~~~~~~
+Contributions are tracked with `git <https://docs.github.com/en/get-started/start-your-journey/about-github-and-git#about-git>`_
+and coordinated with `GitHub <https://docs.github.com/en/get-started/start-your-journey/about-github-and-git#about-github>`_.
+
+In general, a version of the `git-flow <https://nvie.com/posts/a-successful-git-branching-model/>`_
+model is used to navigate parallel development efforts.
+Here's a brief summary:
+
+- Day to day work happens on feature branches on the principle repository or forks. The feature
+  branches may be unstable, and there's no expectation that they are complete.
+  These branches should have a simple name that is indicative of the scope of the work such as
+  ``feature/support_supersonic_tipspeeds``.
+- The ``main`` branch absorbs completed feature branches through pull requests.
+  This branch is expected to be stable and available for general use. However, breaking changes
+  are allowed since the previous release.
+- A tag is added to a commit on the ``main`` branch to note a released version of windIO.
+  Tags typically have a version number such as ``v1.2.3``.
+
+Pull requests
+-------------
+Once a set of changes is ready for review, the author should submit a pull request.
+This signals to the windIO community that a change is coming, and it triggers the review
+process to begin.
+It is the responsibility of the pull request author to convince the reviewers that the change
+is reasonable, complete and an improvement to windIO.
+
+Some guidelines:
+
+- The pull request description should explain the context, motivation, and justification
+  for accepting the change.
+- Executable code should be covered by tests.
+- Data or reference models should include links to their published sources.
+- The pull request's source branch can live either on the main repository or on a fork.
+
+.. Consider this checklist as a starting point to ensuring a pull request is complete:
+
+.. - Executable code is covered by the following tests:
+..   - Test 1
+..   - Test 2
+.. - New components are documented in:
+..   - Location 1
+..   - Location 2
+
+Reviews
+-------
+The review process is as critical to the success of windIO as the code contributions themselves.
+The objective of code reviews is to ensure that windIO stays within its intended scope
+and satisfies its requirements in a stable and sustainable manner.
+
+Reviews should consider the following:
+
+- Code style and formatting
+- Validation: did we make the right thing?
+- Verification: did we make the thing right?
+- How will someone not involved in this pull request understand this
+  change in two months or two years?
+- How does this change impact the complexity of windIO?
+
+.. Code progress and stability
+.. ---------------------------
+.. By default, windIO should be more adaptable / more conservative to change.
+
+
+.. If adaptable:
+.. Non-breaking changes should be evaluated for meeting scope and stability.
+.. However, completeness and rigor are not critical.
+
+.. If conservative:
+.. Any change should be fully reviewed for scope, whole system impact, completeness, and rigor.
+
+
+Roles, Responsibilities and Expectations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The collaborative development process involves various people with distinct roles, and 
+a single person may participate as multiple roles.
+In the context of windIO, the following are identified:
+
+- **Contributor**: Adds to or modifies content in the windIO repository.
+- **Reviewer**: Reviews and critiques changes by contributors from the domain perspective.
+- **Maintainer**: Manages the repository by supporting the review process, managing issues,
+  and generally ensuring the quality of the repository.
+
+All roles are required to work together in the development of windIO, and
+authorship of a change is given to contributors, reviewers, and maintainers.
+Contributors should drive the progress of windIO, reviewers should ensure quality and
+control, and maintainers should serve as a facilitators and enablers.
+There is an implicit tension between these roles, and an effective development process
+requires maintaining a balance.
+
+Contributor Responsibilities
+----------------------------
+Contributors are responsible for communicating their intention to make a change through
+a GitHub Issue or Discussion, and relevant people should be tagged directly for feedback.
+After accepting feedback and updating the proposal, the contributor is responsible for
+implementing the change and submitting a pull request.
+
+It is the responsibility of the contributor to fully describe the change,
+the motivation behind it, and the impact on windIO and the adjacent ecosystem.
+The contributor should work with maintainers to establish a timeline for review and
+incorporating feedback.
+They should also keep a pull request up to date with the latest changes in the target branch.
+While the maintainer will ultimately determine whether a pull request is complete, contributors
+should push the process by providing information and requesting additional reviews.
+
+**Summary: Contributors should strive to make high quality changes and create pull requests that encourage an approval from reviewers.**
+
+Reviewer Responsibilities
+-------------------------
+Reviewers are responsible for providing feedback on the pull request from the perspective
+of the domain included in the change.
+For example, changes to a given area of the ontology should be reviewed by a domain expert
+in that area who understands the contextual impacts.
+Approving a change indicates agreement with the change, and it implies that the reviewer,
+in addition to the contributor, is a relevant person to contact for future questions.
+
+After being assigned to a pull request, a reviewer should coordinate with the contributor and
+maintainers to establish a reasonable review timeline.
+
+**Summary: Reviewers should strive to provide meaningful and constructive feedback that helps the contributor make quality changes and supports the objectives of the windIO project.**
+
+
+Maintainer Responsibilities
+---------------------------
+Maintainers are responsible for ensuring that the windIO repository and processes around 
+and within it continue to serve the windIO community well.
+While the contributor and reviewer roles are activated by a specific pull request,
+the maintainer role is always active.
+Maintainers should keep a high level perspective of the project scope and intent, the
+repository infrastructure, and the processes used to develop windIO.
+This includes managing issues and discussions, reviewing pull requests, and ensuring that
+the repository infrastructure is up to date.
+Maintainers should also work with contributors and reviewers to keep the development process
+moving forward.
+They are responsible for ultimately merging a pull request.
+
+While a pull request is active, maintainers should ensure the following:
+
+- An appropriate reviewer is listed
+- Conflicting works in progress are flagged
+- A tentative timeline for review, design iteration, and merge is established
+
+Otherwise, maintainers should consider the following:
+
+- Dependencies are up to date
+- Documentation sites are functioning
+- Tests are running, passing, and addressing the intended targets
+- Issues and discussions are engaging the relevant people
+- Whether gaps or conflicts have emerged from individual development efforts
+
+**Summary: Maintainers should steer the collaborative development process and provide reviews that support the objectives of the windIO project.**
+
+
+Sequence
+--------
+Here's a typical sequence of events for a contribution:
+
+0. **Identify a need**: *Contributors* identify and characterize a need for a change in windIO.
+   Ideally, this need is discussed with domain experts within the windIO community through a
+   GitHub Issue or Discussion.
+1. **Implement a change**: *Contributors* implement the change in a feature branch.
+2. **Submit a pull request**: When ready for review, *contributors* create a pull request
+   to the windIO repository. A change is ready for review when it is complete, tested,
+   and documented. The pull request should include the context, description and motivation for
+   a description of the change.
+3. **Review and Iteration**: *Reviewers* and *maintainers* provide feedback on the pull request.
+   *Contributors* update the pull request to address feedback. This often occurs over multiple
+   cycles, and it is rare for a pull request to be accepted without changes.
+4. **Merge**: Once the pull request is approved by *reviewers* and the *contributor* signals
+   that it is ready to merge, a *maintainer* does final checks and merges the pull request into
+   the main branch. The change is now part of windIO.