Update documentation surrounding contributions (#344)

Amalgamates and adds new content surrounding contributions from outside
of HPE. Notably, this formalizes an implicit policy that recognizes external
developers as co-authors on the final squash+merge as part of a
Developer Certificate of Origin process.

[ reviewed by @juliaputko, @al-rigazzi, @billschereriii, @ankona ]
[ authored by @ashao ]

CONTRIBUTING.rst

@@ -0,0 +1 @@
+doc/contributing.rst

doc/code_of_conduct.rst

@@ -4,18 +4,50 @@ Code of Conduct
 
 .. _conduct:
 
-Like the technical community as a whole, the SmartSim team and community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching and connecting people.
+Like the technical community as a whole, the SmartSim community is made up of a
+mixture of professionals and volunteers. Members have different roles and work
+on every aspect of the mission - including mentorship, teaching, and communication.
 
-Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to when they are participating within this community and project. These rules apply equally to founders, mentors and those seeking help and guidance.
+Diversity is one of our huge strengths, but it can also lead to tension due to
+differing worldviews. To that end, we have a few ground rules that we ask people
+to adhere to when they are participating within this community and project.
+These rules apply equally to all members regardless of their authority or position
+within the community.
 
-This is not an exhaustive list of things that you cannot do. Rather, take it in the spirit in which it is intended - a guide to make it easier to enrich all of us, the technical community and the conferences and usergroups we hope to guide new speakers to.
+This is not an exhaustive list of things that you cannot do. Rather, take it in
+the spirit in which it is intended - a guide to make it easier to enrich all of
+us, the technical community, and usergroups we hope to guide new speakers to.
 
-This code of conduct applies to all communication. This includes: Slack, GitHub Issues, StackOverflow issues, and other forums such as Zoom, Skype, Google+ Hangouts, etc.
+The code of conduct applies to all communication whether in person or virtual.
+This includes: Slack, GitHub Issues, StackOverflow issues, and other forums such
+as Zoom, Teams, Google Meet, etc.
 
 * **Be welcoming, friendly, and patient.**
-* **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you make will affect users and colleagues, and you should take those consequences into account when making decisions.
-* **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behaviour and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It is important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the SmartSim community should be respectful when dealing with other members as well as with people outside the SmartSim community and with user groups/conferences, usergroup/conference organizers.
-* **Be careful in the words that you choose.** Remember that sexist, racist, and other exclusionary jokes can be offensive to those around you. Be kind to others. Do not insult or put down other participants. Behave professionally. Remember that harassment and sexist, racist, or exclusionary jokes are not appropriate for the community.
-* **When we disagree, we try to understand why.** Disagreements, both social and technical, happen all the time and SmartSim is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we are different. The strength of SmartSim comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint does not mean that they are wrong. Do not forget that it is human to err and blaming each other does not get us anywhere. Rather, offer to help resolving issues and to help learn from mistakes.
+* **Be considerate.**
+Your work will be used by other people, and you in turn will depend on the work
+of others. Any decision you make will affect users and colleagues, and you
+should take those consequences into account when making decisions.
+* **Be respectful.**
+Not all of us will agree all the time, but disagreement is no excuse for poor
+behaviour and poor manners. We might all experience some frustration now and
+then, but we cannot allow that frustration to turn into a personal attack. It is
+important to remember that a community where people feel uncomfortable or
+threatened is not a productive one. Members of the SmartSim community should be
+respectful when dealing with other members as well as with people outside the
+SmartSim community.
+* **Be careful in the words that you choose.**
+Sexist, racist, and other exclusionary jokes and comments can be offensive to
+those around you. Be kind to others. Do not insult or put down other
+participants. Behave professionally. Remember that harassment and sexist,
+racist, or exclusionary jokes are not appropriate for the community.
+* **When we disagree, we try to understand why.**
+Disagreements, both social and technical, are a natural part of collaborative
+development. It is important that we resolve disagreements and differing views
+constructively. Remember that we are different. The strength of SmartSim comes
+from its varied community, people from a wide range of backgrounds. Different
+people have different perspectives on issues. Being unable to understand why
+someone holds a viewpoint does not mean that they are wrong. Do not forget that
+it is human to err and blaming each other does not get us anywhere. Rather,
+offer to help resolve issues and to help learn from mistakes.
 
 Original text courtesy of the `Speak Up! project <http://web.archive.org/web/20141109123859/http://speakup.io/coc.html>`_.

doc/contributing.rst

@@ -0,0 +1,98 @@
+
+*********
+Contributing Guide
+******************
+
+Thanks for you interest in joining the SmartSim community. While SmartSim is
+primarily developed by a team of engineers at Hewlett Packard Enterprise, we
+benefit greatly from community contributions and discussions. Please feel free
+to reach out; we are always open to hearing about your science and engineering
+questions.
+
+Code of Conduct
+---------------
+All users, contributors, and developers of SmartSim are expected to treat each
+other fairly and with respect. Please review our :ref:`Code of Conduct
+<conduct>` which highlights what this expectation means for the community.
+
+Need Help?
+----------
+We encourage and welcome usage questions and bug reports from all users,
+especially those who are new to SmartSim. There are a few things you can do to
+improve the likelihood of quickly getting a good answer.
+
+1. **It is important to ask questions in the right place.**
+While we understand people's desires for privacy, we strongly prefer the use of
+GitHub issues (feature requests, bug reports or Stack Overflow posts (usage
+questions, best practices) due to their discoverability by future users as
+opposed to private communications like Slack or email. Slack chat should be
+reserved for developer and community discussion. Email is preferred for more
+sensitive items.
+
+2. **Please ask only in one place.** Please restrict yourself to posting your
+question in only one place (likely Stack Overflow or GitHub) and don’t post in
+both.
+
+3. **A minimal example is extremely helpful!** It is ideal to create `minimal,
+complete, verifiable examples
+<https://stackoverflow.com/help/minimal-reproducible-example>`_. This
+significantly reduces the time that responders spend understanding your
+situation, resulting in higher quality answers more quickly. Mathew Rocklin has
+`this great blogpost
+<http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports>`_ about
+crafting minimal bug reports. Questions with examples have a much higher
+likelihood of being answered.
+
+How to contribute
+-----------------
+We welcome contributions from the broader community. These generally fall under
+two categories:
+
+- Developments to the main codebases: These contributions directly modify the
+SmartSim and SmartRedis repositories to fix bugs in the code, improve
+the documentation, or add new features. Before embarking on major development,
+please contact the developers first to make sure that your proposal aligns
+with the internal development by opening an issue or reach out to us. Please
+follow the :ref:`Developer Guidelines <developer_guide>`.
+
+- Applications of SmartSim: Many of our users build scientific/engineering
+applications using SmartSim and SmartRedis. Please feel free to make
+contributions to the :ref:`SmartSim Zoo <smartsim_zoo>`.
+
+In both cases, contributors can expect the following:
+
+- A quick response to your pull requests detailing why we are accepting or
+rejecting your contribution
+
+- If we accept your contribution, a SmartSim developer will be assigned to help
+bring your contribution into the codebases by testing it across a variety of
+platforms and ensuring code quality.
+
+- You will be credited as a co-author when the contribution is merged
+
+.. note::
+    The last point serves as a `Developer Certificate of Origin<https://developercertificate.org/>`_.
+    More specifically, we will ask contributors to signoff on the final state
+    of the PR before merging. This signoff will then be propagated into the
+    final squash merge commit.
+
+How to Connect?
+---------------
+Questions and discussion about SmartSim should be directed to the following:
+
+1. **Using SmartSim** - If you have questions on using SmartSim please `post
+them to Stack Overflow <https://stackoverflow.com/questions/tagged/smartsim>`_
+and tag them with the #smartsim tag.
+
+2. **SmartSim Contributor Development Chat** - We monitor `Slack for SmartSim
+<https://join.slack.com/t/craylabs/shared_invite/zt-nw3ag5z5-5PS4tIXBfufu1bIvvr71UA>`_
+for contribution development questions.
+
+3. **Report a Bug or Request a Feature** - Features and Bugs are managed
+through GitHub. For issues related to `SmartSim post here
+<https://github.com/CrayLabs/SmartSim/issues>`_. For issues related to
+`SmartRedis post here <https://github.com/CrayLabs/smartredis/issues>`_.
+
+4. **Contact the Development Team** - For all other inquiries including
+collaboration opportunities, please contact SmartSim at hpe dot com.
+

doc/developer.rst

@@ -3,8 +3,10 @@
 Developer
 *********
 
-This section details common practices and tips for contributors
-to SmartSim and SmartRedis.
+.. _developer_guide:
+
+This section details common practices and tips for contributors to SmartSim and
+SmartRedis.
 
 ==========================
 Building the Documentation

doc/index.rst

@@ -13,8 +13,8 @@
    overview
    installation_instructions/basic
    installation_instructions/platform
-   community
-   contributing_examples
+   contributing
+   smartsim_zoo
 
 .. toctree::
    :maxdepth: 2

doc/contributing_examples.rst → doc/smartsim_zoo.rst

@@ -2,37 +2,50 @@
 Contributing Examples
 *********************
 
+.. _smartsim_zoo:
+
 What Is the SmartSim Zoo?
 #########################
-Given that SmartSim is a community developed and maintained project, we have introduced
-a `SmartSim Example Zoo <https://github.com/CrayLabs/SmartSim-Zoo>`_ that contains CrayLabs and user contributed examples of using SmartSim
-for various simulation and machine learning applications.
+
+Given that SmartSim is a community developed and maintained project, we have
+introduced a `SmartSim Example Zoo <https://github.com/CrayLabs/SmartSim-Zoo>`_
+that contains CrayLabs and user contributed examples of using SmartSim for
+various simulation and machine learning applications.
 
 The Two Categories of the SmartSim Zoo
 **************************************
+
  1. SmartSim Deployments (running SmartSim on various HPC Systems)
 
-  * The source code for the repository serves the purpose of showing diverse examples of how to get SmartSim running on
-    different HPC Systems. If you are looking for working examples on a specific machine, then the source code in the
-    SmartSim-Zoo repository is for you. The SmartSim development team strives to keep these examples updated with each
-    release so that users will always have robust examples for their needs.
+  * The source code for the repository serves the purpose of showing diverse
+  * examples of how to get SmartSim running on
+  different HPC Systems. If you are looking for working examples on a specific
+  machine, then the source code in the SmartSim-Zoo repository is for you. The
+  SmartSim development team strives to keep these examples updated with each
+  release so that users will always have robust examples for their needs.
 
  2. SmartSim Applications (completed projects that use SmartSim)
 
-  * The README for the repository describes some of the larger applications of SmartSim. These examples fall under two categories:
-    examples by paper and examples by simulation model. The examples by paper are based on existing research papers, and the examples
-    by simulation models are integrations of SmartSim with existing simulation models.
+  * The README for the repository describes some of the larger applications of
+  * SmartSim. These examples fall under two categories:
+  examples by paper and examples by simulation model. The examples by paper are
+  based on existing research papers, and the examples by simulation models are
+  integrations of SmartSim with existing simulation models.
 
 How To Contribute
 #################
-We support, encourage, and welcome all contributions to the `SmartSim Zoo <https://github.com/CrayLabs/SmartSim-Zoo>`_ repository. Instructions for
-contributing examples varies whether you are contributing a SmartSim deployment or a SmartSim application.
+
+We support, encourage, and welcome all contributions to the `SmartSim Zoo
+<https://github.com/CrayLabs/SmartSim-Zoo>`_ repository. Instructions for
+contributing examples varies whether you are contributing a SmartSim deployment
+or a SmartSim application.
 
  1. Contributing SmartSim Deployment Examples
 
-  * For contributing examples of SmartSim running on a HPC System, we ask that you include a description and all references to code and
-    relevant previous implementations or open source code that the work is based on for the benefit of anyone who would like to
-    try out your example.
+  * For contributing examples of SmartSim running on a HPC System, we ask that
+  you include a description and all references to code and relevant previous
+  implementations or open source code that the work is based on for the benefit
+  of anyone who would like to try out your example.
 
  2. Contributing SmartSim Application Examples
 
@@ -49,8 +62,10 @@ contributing examples varies whether you are contributing a SmartSim deployment
 
 Existing Examples
 #################
-The subsequent tables summarize the examples provided in the SmartSim Zoo. You can find a more detailed
-description of each example in the `SmartSim Zoo <https://github.com/CrayLabs/SmartSim-Zoo>`_.
+
+The subsequent tables summarize the examples provided in the SmartSim Zoo. You
+can find a more detailed description of each example in the `SmartSim Zoo
+<https://github.com/CrayLabs/SmartSim-Zoo>`_.
 
 .. list-table:: SmartSim Deployment Examples
    :widths: 50 100
@@ -94,15 +109,19 @@ description of each example in the `SmartSim Zoo <https://github.com/CrayLabs/Sm
 Summary of SmartSim Application Examples
 ########################################
 
- * **DeepDriveMD:** Based on the original DeepDriveMD work, extended to orchestrate complex workflows
-   with coupled applications without using the filesystem for exchanging information.
+* **DeepDriveMD:** Based on the original DeepDriveMD work, extended to
+orchestrate complex workflows with coupled applications without using the
+filesystem for exchanging information.
 
- * **TensorFlowFoam:** Uses TensorFlow inside of OpenFOAM simulations using SmartSim. Displays SmartSim's
-   capability to evaluate a machine learning model from within a simulation with minimal external library
-   code and minimal API calls.
+* **TensorFlowFoam:** Uses TensorFlow inside of OpenFOAM simulations using
+SmartSim. Displays SmartSim's capability to evaluate a machine learning model
+from within a simulation with minimal external library code and minimal API
+calls.
 
- * **ML-EKE:** Runs an ensemble of simulations all using the SmartSim architecture to replace a
-   parameterization (MEKE) within each global ocean simulation (MOM6).
+* **ML-EKE:** Runs an ensemble of simulations all using the SmartSim
+architecture to replace a parameterization (MEKE) within each global ocean
+simulation (MOM6).
 
- * **LAMMPS + SmartSim:** Implementation of a ``SMARTSIM`` dump style which uses the SmartRedis clients to stream
-   data to an Orchestrator database created by SmartSim.
+* **LAMMPS + SmartSim:** Implementation of a ``SMARTSIM`` dump style which uses
+the SmartRedis clients to stream data to an Orchestrator database created by
+SmartSim.