ENH: add extra files to project structure (#96)

jorgepiloto · web-flow · commit 0df8489be5af · 2022-05-13T14:57:30.000+02:00
diff --git a/doc/source/guidelines/test_practices.rst b/doc/source/guidelines/test_practices.rst
@@ -284,8 +284,8 @@ Testing Framework
 For consistency, PyAnsys tools and libraries should use either the `unittest
 <https://docs.python.org/3/library/unittest.html>`_ or `pytest
 <https://docs.pytest.org/>`_ frameworks for unit testing. As described in
-:ref:`Required Files for a PyAnsys Project`, unit tests should be placed in the ``tests``
-directory in the library's root directory::
+:ref:`Required Files`, unit tests should be placed in the ``tests`` directory in
+the library's root directory::
 
    tests/
        test_basic.py
diff --git a/doc/source/packaging/code/changelog_file.md b/doc/source/packaging/code/changelog_file.md
@@ -0,0 +1,29 @@
+# Changelog
+
+
+## <pyproduct-library> <version X.Y.Z> - <Release Date YYYY-MM-DD>
+
+### Bugs Fixed
+
+* Brief description of the bug. Link to the associated issue and pull request.
+* ... 
+
+### New Features
+
+* Brief description of the feature. Link to the associated issue and pull request.
+* ...
+
+### Doc Improvements
+
+* Brief description of the improvement. Link to the associated issue and pull request.
+* ...
+
+### Contributors
+
+* <Name of the contributor> - <Email of the contributor>
+* ...
+
+
+## <pyproduct-library> <version X.Y.Z> - <Release Date YYYY-MM-DD>
+
+...
diff --git a/doc/source/packaging/code/code_of_conduct_file.md b/doc/source/packaging/code/code_of_conduct_file.md
@@ -0,0 +1,65 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our
+project and our community a harassment-free experience for everyone,
+regardless of age, body size, disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual
+  attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at
+https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
diff --git a/doc/source/packaging/code/contributing_file.md b/doc/source/packaging/code/contributing_file.md
@@ -0,0 +1,7 @@
+# Contributing
+
+Please, refer to the [PyAnsys Developer's Guide] for contributing to this project.
+
+[PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/index.html
+
+<!-- Additional information for your project goes below this line -->
diff --git a/doc/source/packaging/diag/pyproduct_library_structure_diag.rst b/doc/source/packaging/diag/pyproduct_library_structure_diag.rst
@@ -46,14 +46,26 @@
            label="tests", shape="folder"
          ]
 
-         readme [
-           label="README.rst", shape="file"
+         changelog [
+           label="CHANGELOG.md", shape="file"
+         ]
+
+         code_of_conduct [
+           label="CODE_OF_CONDUCT.md", shape="file"
+         ]
+
+         contributing [
+           label="CONTRIBUTING.md", shape="file"
          ]
 
          license [
            label="LICENSE", shape="file"
          ]
 
+         readme [
+           label="README.rst", shape="file"
+         ]
+
          pyproject [
            label="pyproject.toml", shape="file"
          ]
@@ -67,6 +79,9 @@
          pyproduct_library -> src;
          pyproduct_library -> tests;
          pyproduct_library -> license;
+         pyproduct_library -> changelog;
+         pyproduct_library -> code_of_conduct;
+         pyproduct_library -> contributing;
          pyproduct_library -> readme;
          pyproduct_library -> pyproject;
          pyproduct_library -> setup;
diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst
@@ -97,8 +97,8 @@ sub-packages, while a Python Library is a collection of Python packages. Figure
 .. include:: diag/python_library_diag.rst
 
 
-Required Files for a PyAnsys Project
-====================================
+Required Files
+==============
 
 The structure of any PyAnsys library contains these files and directories:
 
@@ -199,6 +199,44 @@ This is the preferred way of naming directories and files inside the
 ``tests/`` directory.
 
 
+The ``CHANGELOG.md`` file
+-------------------------
+
+This file is used to collect the new features, fixed bugs, documentation
+improvements and new contributors. It allows to have a quick-view on the latest
+enhancements to the project.
+
+.. literalinclude:: code/changelog_file.md
+   :language: markdown
+
+
+The ``CODE_OF_CONDUCT.md`` file
+-------------------------------
+
+This file is used to specify how users, developers and maintainers should behave
+while working in the project. PyAnsys projects usually adopt the ``Contributor
+Covenant Code of Conduct``, which is very popular across open-source projects.
+
+.. literalinclude:: code/code_of_conduct_file.md
+   :language: markdown
+
+
+The ``CONTRIBUTING.md`` file
+----------------------------
+This file is used as a quick entry-point for developers wiling to contribute to
+the project. It usually provides references to:
+
+- Where the source code of the project is hosted.
+- Which steps need to be followed to install the software in "development" mode.
+- Additional ways of contributing to the source code.
+
+Ideally, the ``CONTRIBUTING.md`` file for a PyAnsys project should be pointing
+towards the `PyAnsys Developer's Guide <https://dev.docs.pyansys.com/index.html>`_.
+
+.. literalinclude:: code/contributing_file.md
+   :language: markdown
+
+
 The ``LICENSE`` File
 --------------------
 
