diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index d6eb658d..c6e00d4a 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -2,102 +2,243 @@ Development Practices ===================== +This page explains how PyAnsys development is conducted. When +contributing directly to PyAnsys libraries, use these general +coding paradigms: + +#. Follow the `Zen of Python `__. + As silly as core Python developers are sometimes, there's much to be + gained by following the basic guidelines listed in PEP 20. As suggested + in these guidelines, focus on making your additions intuitive, novel, + and helpful for PyAnsys library users. When in doubt, use ``import this``. + For Ansys code quality standards, see :ref:`coding_style`. + +#. Document your contributions. Include a docstring for any added + function, method, or class, following `numpydocs docstring `_ + guidelines and PyAnsys documentation standards <#Documentation Standards>. + Always provide at least one simple use case for a new feature. + +#. Test your contribution. Because Python is an interpreted language, if + it's not tested, it's probably broken. At the minimum, include a unit + test for each new feature within the ``tests`` directory. Ensure that + each new method, class, or function has reasonable (>80%) coverage. + See `Testing <#Testing>`__ for automating testing. + +#. Do not include any datasets for which a license is not available + or commercial use is prohibited. + +#. Review our `Code of Conduct `_. + +Contributing Through GitHub +--------------------------- +To submit new code to a PyAnsys Library: + +#. `Fork `_ + the respective library's GitHub repository and then clone + the forked repository to your computer. + +#. In your local repository, create a branch. See `Branching Model <#Branching Model>`__. + +#. Add your new feature and commit it locally. Be sure to commit + frequently as the ability to revert to past commits is often helpful, + especially if your change is complex. + +#. Test often. See `Testing <#Testing>`__ for automating testing. + +#. When you are ready to submit your code, create a pull request (PR) + by following the steps in the next section. + +Creating a Pull Request +~~~~~~~~~~~~~~~~~~~~~~~ +Once you have tested your branch locally, create a PR and target your +merge to ``main``. This will automatically run CI testing and verify +that your changes will work across all supported platforms. + +For code verification, someone from the development team for the PyAnsys library +will review your code to verify that it meets our standards. Once your code +is approved, if you have write permission, you may merge the PR branch. If you +don't have write permission, the reviewer or someone else with write permission +will merge and delete the PR branch. + +If your PR branch is a ``fix/`` branch, do not delete it because it may be necessary to +merge your PR branch with the current release branch. See the next section for branch +naming conventions. + +Branch Naming Conventions +~~~~~~~~~~~~~~~~~~~~~~~~~ +To streamline development, we have the following requirements for naming +branches. These requirements help core developers know what kind of +changes any given branch is introducing before looking at the code. + +- ``fix/``: any bug fixes, patches, or experimental changes that are + minor +- ``feat/``: any changes that introduce a new feature or significant + addition +- ``junk/``: for any experimental changes that can be deleted if gone + stale +- ``maint/``: for general maintenance of the repository or CI routines +- ``doc/``: for any changes only pertaining to documentation +- ``no-ci/``: for low-impact activity that should not trigger the CI + routines +- ``testing/``: improvements or changes to testing +- ``release/``: releases (see below) + +Testing +~~~~~~~ +When making changes, periodically test locally before creating a PR. +Because the following tests are executed after any commit or PR, we +ask that you perform the following procedure locally to track down +any new issues from your changes. -This section explains how development is conducted in PyAnsys -repositories. Please follow the practices outlined here when -contributing directly to PyAnsys libraries. +#. Install requirements for testing: +.. code:: -General Development Procedures ------------------------------- + pip install -r requirements_test.txt -To submit new code to a PyAnsys, first `fork `_ -the repository (for example `PyMAPDL `_) -and then clone the forked repository to your local environment. Next, create a new branch based on the -`Branch Naming Conventions Section <#branch-naming-conventions>`__ in -your local repository. +#. Run the primary test suite and generate a coverage report: -Next, add your new feature and commit it locally. Be sure to commit -often as it is often helpful to revert to past commits, especially if -your change is complex. Also, be sure to test often. See the `Testing -Section <#testing>`__ below for automating testing. +.. code:: -When you are ready to submit your code, create a pull request by -following the steps in `Creating a New Pull Request <#creating-a-new-pull-request>`__. + pytest -v --cov _unittest -Be sure to review these topics: +Spelling and Code Style +~~~~~~~~~~~~~~~~~~~~~~~ +If you are using Linux or Mac OS, run spelling and coding style checks: -#. `Branching Section <#Branching Model>`__ -#. Testing standards. -#. Documentation standards. See :ref:`api_documentation`. -#. Code quality standards. See :ref:`coding_style`. +.. code:: + cd + pip install -r requirements_style.txt + make -Guidelines -~~~~~~~~~~ +Misspelled words will be reported. You can add words to be ignored to +the ``ignore_words.txt`` file. For example, for PyMAPDL, this file looks +like this: -Consider the following general coding paradigms when contributing: +... code:: -1. Follow the `Zen of Python `__. - As silly as the core Python developers are sometimes, there's much to - be gained by following the basic guidelines listed in PEP 20. - Without repeating them here, focus on making your additions - intuitive, novel, and helpful for users. + codespell ./ "*.pyc,*.txt,*.gif,*.png,*.jpg,*.js,*.html,*.doctree,*.ttf,*.woff,*.woff2,*.eot,*.mp4,*.inv,*.pickle,*.ipynb,flycheck*,./.git/*,./.hypothesis/*,*.yml,./doc/build/*,./doc/images/*,./dist/*,*~,.hypothesis*,./doc/source/examples/*,*cover,*.dat,*.mac,\#*,build,./docker/mapdl/v211,./factory/*,./ansys/mapdl/core/mapdl_functions.py,PKG-INFO" -I "ignore_words.txt" - When in doubt, ``import this``. +Documentation +------------- +Documentation for a PyAnsys library is generated from three sources: -2. **Document it**. Include a docstring for any function, method, or - class added. Follow the `numpydocs docstring - `_ - guidelines, and always provide an example of simple use cases for - new features. +- Docstrings from the library's classes, functions, and modules using + `sphinx.ext.autodoc `_. +- reStructuredText (RST) files from ``doc/`` +- Examples from ``examples/`` -3. **Test it**. Because Python is an interpreted language, if it's not - tested, it's probably broken. At the minimum, include unit tests - for each new feature within the ``tests`` directory. Ensure that - each new method, class, or function has reasonable (>80%) coverage. +General usage information and API descriptions should be placed within +``doc/source`` and docstrings. Full examples should be placed in +``examples/``. + +Adding a New Example +~~~~~~~~~~~~~~~~~~~~ +Examples come in two formats: + +- Basic code snippets demonstrating some functionality +- Full-fledged standalone examples meant to be run as individual downloadable scripts + +While basic code snippets should be placed in the ``doc/source`` directory, full-fledged +standalone examples must be placed in the ``examples`` directory at the root of the repository. + +When adding a standalone example, you add it to an applicable subfolder in the ``examples`` +directory. If none of the existing directories match the category of your example, create +a new subfolder with a ``README.txt`` file describing the new category. As these examples +are built using the Sphinx gallery extension, you must follow `Sphinx gallery coding guidelines _`. + +PyMAPDL provides a self-demonstrating example of how to `add an example reference key `_. + +Documentation Style and Organization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Docstrings should follow `numpydocs docstring `_ +guidelines. Documentation within the ``doc/`` directory use the reStructuredText. +(RST) format. Examples within the ``examples/`` directory should be PEP8-compliant +and will be compiled dynamically during the build process. Always ensure that +examples run properly locally as they will be verified through the CI performed +via GitHub Actions. + +Documentation for the latest stable release of a PyAnsys libary is accessible +from its repository. You can access the latest development version of the +documentation tracking the ``main`` branch by adding the prefix ``dev.`` to +the URL for the latest stable release. For example, the URL for the latest +stable release of the PyAEDT documentation is +``_, and the URL for the latest development +version of this documentation is ``_. The +latest development version is kept up-to-date automatically via GitHub actions. + +Building the Documentation Locally +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can build and verify a library's HTML documentation locally by installing +Sphinx and other documentation build dependencies. + +#. Optionally install the library in development mode: + +.. code:: + + pip install -e . + +#. Install the build requirements for documentation: -Additionally, do not include any data sets for which a license -is not available or commercial use is prohibited. +.. code:: -Licensing -~~~~~~~~~ + pip install -r requirements_docs.txt -All contributed code will be licensed under the MIT License found in -the repository. If you did not write the code yourself, it is your -responsibility to ensure that the existing license is compatible and -included in the contributed files. You must obtain permission from the -original author to relicense the code. -See :ref:`license_file` for more details. +#. If running on Linux/Mac OS, build the documentation: +.. code:: + + make -C doc html + +Otherwise, if running on Windows, build the documentation: + +.. code:: + + cd doc + make.bat html + +#. After documentation builds successfully locally, use your + browser to open the file ``index.html`` in ``doc/_build/html/`` + to review it. + +Continuous Integration and Continuous Delivery (CI/CD) +------------------------------------------------------ + +A PyAnsys library uses continuous integration (CI) and continuous delivery (CD) +to automate building, testing, and deployment tasks. The CI pipeline is +deployed on both GitHub Actions and Azure Pipelines and performs the following +tasks: + +- Module wheel build +- Core API testing +- Spelling and style verification +- Documentation build Branching Model --------------- -This project has a branching model that enables rapid development of -features without sacrificing stability and closely follows the -`Trunk Based Development `_ approach. - -Descriptions follow for the main features of the branching model. +The branching model for a PyAnsys library enables rapid development of +features without sacrificing stability. The model closely follows the +`Trunk Based Development `_ approach: - The `main` branch is the primary development branch. All features, - patches, and other branches should be merged here. While all pull - requests (PRs) should pass all applicable CI (Continuous Integration) - checks, this branch might be functionally unstable if changes have - introduced unintended side-effects or bugs that were not caught through - unit testing. -- There will be one or many `release/` branches based on minor + patches, and other branches should be merged here. While all PRs + should pass all applicable CI checks, this branch might be functionally + unstable if changes have introduced unintended side effects or bugs + that were not caught through unit testing. +- There will be one or many ``release/`` branches based on minor releases (for example, ``release/0.2``) that contain a stable version of the code base that is also reflected on PyPI. Hotfixes from - `fix/` branches should be merged both to main and to these + ``fix/`` branches should be merged both to ``main`` and to these branches. When creating a new patch release is necessary, these - release branches will have their ``__version__.py`` updated and be - tagged with a patched semantic version (for example, ``0.2.1``). This - triggers CI to push to PyPi and allow us to rapidly push hotfixes + release branches will have their ``__version__.py`` file updated and + be tagged with a patched semantic version (for example, ``0.2.1``). + This triggers CI to push to PyPi and allow us to rapidly push hotfixes for past versions without having to worry about untested features. - When a minor release candidate is ready, a new ``release`` branch will be created from ``main`` with the next incremented minor version - (for example, ``release/0.2``), This ``release`` branch will be thoroughly + (for example, ``release/0.2``). This ``release`` branch will be thoroughly tested. When deemed stable, it will be tagged with the version (``0.2.0`` in this case) and merged with ``main`` if any changes were pushed to it. Feature development then continues on ``main`` and any hotfixes will now @@ -109,19 +250,20 @@ Descriptions follow for the main features of the branching model. Release Procedures ------------------ -Major and Minor -~~~~~~~~~~~~~~~ -Procedures follow for major and minor releases. +Major and Minor Release Steps +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Release procedures follow for major and minor releases. -#. Create a new branch from the `main` branch with name +#. Create a new branch from the ``main`` branch with the name ``release/MAJOR.MINOR`` (for example, ``release/0.2``). -#. Locally run all tests as outlined in :ref:`testing` and ensure all - are passing. +#. Locally run all tests as outlined in `Testing <#Testing>`_ and + ensure that all are passing. -#. Locally test and build the documentation with link checking to make - sure no links are outdated. Be sure to run ``make clean`` to ensure no - results are cached. +#. Locally test and build the documentation with link checking to + ensure that no links are outdated. + +#. Run ``make clean`` to ensure that no results are cached. .. code:: @@ -133,36 +275,36 @@ Procedures follow for major and minor releases. the examples for any obvious issues. #. Update the version numbers in - ``ansys///_version.py`` and commit it. Push the + ``ansys///_version.py`` and commit this file. Push the branch to GitHub and create a new PR for this release that merges - it to ``main``. Development to ``main`` should be limited while - effort is focused on the release. + it to ``main``. While effort is focused on the release, development + to ``main`` should be limited. -#. The community and Ansys developers must now functionally test the - new release. It is best to locally install this branch and use it in - production. Any bugs identified should have their hotfixes pushed to +#. Wait for the PyAnsys developers and community to functionally test the + new release. Testors should locally install this branch and use it in + production. Any bugs that they identify should have their hotfixes pushed to this release branch. -#. When the branch is deemed as stable for public release, the PR is merged - to `main` branch, which is then tagged with a `MAJOR.MINOR.0` release. + When the branch is deemed as stable for public release, the PR is merged + to ``main``, which must then be tagged with a ``MAJOR.MINOR.0`` release. The release branch will not be deleted. - - Tag the release with: + +#. Tag the release: .. code:: - git tag v + git tag v git push origin --tags #. Create a list of all changes for the release. It is often helpful - to see the differences from the last tag and the ``main`` branch - using `GitHub's compare feature`_ tool. Be sure to acknowledge new - contributors by their GitHub username and place mentions where - appropriate if a specific contributor is to be thanked for a new - feature. + to leverage GitHub's compare feature to see the differences from + the last tag and the ``main`` branch. Be sure to acknowledge new + contributors by their GitHub usernames and place mentions where + appropriate if specific contributors are to be thanked for new + features. -#. Place your release notes from the previous in the release section within the GitHub repository. See - `GitHub Releases`_ +#. Place your release notes from the previous step in ``Releases`` + in the GitHub repository. See `GitHub Releases`_. .. _GitHub Releases: https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository .. _GitHub's compare feature: https://github.com/pyansys/pymapdl/compare @@ -173,25 +315,21 @@ Patch Release Steps Patch releases are for critical and important bug fixes that cannot or should not wait until a minor release. These are the steps for a patch release: -1. Push the necessary bug fixes to the applicable release branch. - This will generally be the latest release branch (`release/MAJOR.MINOR`). +#. Push the necessary bug fixes to the applicable release branch. + This will generally be the latest release branch (for example, + ``release/MAJOR.MINOR``). -2. Update ``__version__.py`` with the next patch increment - (`MAJOR.MINOR.PATCH`), commit it, and open a PR to merge with the - release branch. This gives the developers and community - an opportunity to validate and approve the bug fix release. Any +#. Update the ``__version__.py`` file with the next patch increment + (``MAJOR.MINOR.PATCH``), commit it, and open a PR to merge with the + release branch. This gives the PyAnsys developers and community + an opportunity to validate and approve the bug fix release. Any additional hotfixes should be outside of this PR. -3. When approved, merge with the release branch, but not `main` as - there is no reason to increment the version of the `main` branch. - Then, create a tag from the release branch with the applicable - version number (see above for the correct steps). +#. When the PR is approved, merge it with the release branch, but not with + ``main`` as there is no reason to increment the version of the ``main`` branch. -4. If deemed necessary, add a release notes page. +#. Create a tag from the release branch with the applicable version number + as described in the previous section. - -.. _testing: - -Testing -------- - +4. If deemed necessary, create and add release notes as described in the + previous section. diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index dbbca27c..8d98bfda 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -2,83 +2,97 @@ Contributing ============ -This page provides a quick start guide for anyone who wants to start -contributing to a PyAnsys library. +Ansys welcomes all PyAnsys code contributions and wants you to +understand how to contribute. While we maintain PyAnsys libraries +and thoroughly review all submissions, we want to foster a community +that supports user questions and develops new features to make +our libraries powerful tools for all users. As such, we +encourage you to submit questions, report bugs, request new +features, contribute code, and start discussions. + +This page provides general information about contributing to a +PyAnsys library. Contribution information specific to a particular +library appears on the ``Contributing`` page in the respective +library's documentation, including: + +- Instructions for cloning the source repository from GitHub +- URL to the library`s ``Issues`` page +- Email address for the library's support team + +For convenience, here are URLs for the ``Issues`` page of +applicable repositories: -We welcome all code contributions and hope that this developer's guide -facilitates an understanding of the PyAnsys code repository. It is important to -note that while Ansys maintains all PyAnsys libraries and thoroughly reviews all -submissions before merging, our goal is to foster a community that can support -user questions and develop new features to make PyAnsys libraries powerful tools -for all users. As such, we welcome and encourage the submittal of questions and -code to this repository and all PyAnsys library repositories. +- `PyAEDT Issues `_ +- `PyDPF-Core Issues `_ +- `PyDPF-Post Issues `_ +- `PyMAPDL Issues `_ +- `PyMAPDL Reader Issues `_ +The overall PyAnsys project support team can be reached at +pyansys.support@ansys.com. Someone will either respond or direct the +message to the respective library's support team. -Contributing New Code +Submitting Questions --------------------- -If you have an idea for improving a PyAnsys library, consider first -creating an issue as a feature request. We will then use this thread -to discuss how best to implement the contribution. - -Once you are ready to start coding, see the -:ref:`best_practices` section for more information on how to -develop your code and adhere to PyAnsys repository standards. - - -Feature Requests ----------------- -We encourage users to submit ideas for improvements to PyAnsys libraries. -To suggest an improvement, create an issue on the Issues page for the -respective PyAnsys library and tag it with a ``Feature Request`` label. - -Use a descriptive title and provide ample background information to help -the community implement the desired functionality. For example, if you -would like a reader for a specific file format, provide a link to -documentation of this file format and possibly provide some sample files -and screenshots. We will use the issue thread as a place to discuss and -provide feedback. - +For general or technical questions about a PyAnsys library, its +applications, or software usage, create issues on the respective +library's ``Issues`` page. This allows PyAEDT developers and +community members with the needed expertise to collectively address +them. It also makes their responses available to all users. Reporting Bugs -------------- -If you encounter a bug or your workflow crashes while using a PyAnsys -library, please create an issue on the issues page of the respective -PyAnsys library and tag it with an appropriate label so that it can be -promptly addressed. When reporting an issue, be as descriptive as possible -so that the issue can be reproduced. Whenever possible, provide a traceback, -screenshot, and sample files to help us address the issue. - - - -Issues ------- -For general or technical questions about a PyAnsys library, its applications, or -about software usage, you can create issues for the applicable repository at: - -- `PyAEDT Issues `_ -- `PyMAPDL Issues `_ -- `DPF-Core Issues `_ - -This way, the community or PyAnsys developers can collectively address -them. The project support team can be reached at -pyansys.support@ansys.com. Someone will respond or direct the -message accordingly. - - -Discussions -~~~~~~~~~~~ -General questions regarding development practices should be raised as -discussions in the repository for the corresponding PyAnsys library -rather than as issues. For example, general questions about PyMAPDL should be raised -in the `PyMAPDL Discussions `_. -Issues can be spun out of discussions depending on what is decided, but general -questions should start as discussions where possible. +If you encounter a bug or your workflow crashes while using a +PyAnsys library, create an issue on the respective library's +``Issues`` page and tag it with an appropriate label so that it +can be promptly addressed. When reporting an issue, be as descriptive +as possible so that the issue can be reproduced. Whenever possible, +provide a traceback, screenshots, and sample files to help us address +the issue. + +Requesting New Features +----------------------- +We encourage you to submit ideas for improvements to PyAnsys libraries. +To suggest a new feature, create an issue on the respective library's +``Issues`` page and tag it with a ``Feature Request`` label. Use a +descriptive title and provide ample background information to help the +community implement the desired functionality. For example, if you +would like a reader for a specific file format, provide a link to +documentation for this file format and possibly provide some sample files +and screenshots. We will use the issue thread as a place to discuss the +feature request and provide feedback. +Contributing New Code +--------------------- +If you have an idea for improving a PyAnsys library, consider first +creating an issue for a new feature request. We will then use this thread +to discuss how best to implement the contribution. -Installing from Source ----------------------- -You can clone the source repository from GitHub and install the -latest version in development mode by running: +Once you are ready to start coding, see: + +- :ref:`development_practices` for information on how development is + conducted in PyAnsys repositories +- :ref:`best_practices` for information on how to style and format your + code to adhere to PyAnsys standards + +Starting Discussions +-------------------- +In the repository for the respective PyAnsys library, you should raise +general questions regarding development practices as discussions rather +than issues. For example, raise general questions about PyMAPDL +in `PyMAPDL Discussions `_. +Depending on what is decided, issues can be spun out of general discussions. + +.. note:: + The discussions feature is still in beta on GitHub, so this may + change in the future. + +Cloning the Source Repository +----------------------------- +As mentioned earlier, specific instructions for cloning a source +repository from GitHub appear on the ``Contributing`` page in the +respective library's documentation. Here is a summary of the code +for cloning and installing the latest version in development: .. code:: @@ -86,7 +100,8 @@ latest version in development mode by running: cd pip install -e . -For example: +For example, here is the code for cloning and installing the latest version +of PyMAPDL: .. code:: @@ -94,19 +109,16 @@ For example: cd pymapdl pip install -e . -Consider creating a fork of the repository if you want to eventually -push a contribution to the official PyAnsys repository. - -.. https://docs.github.com/en/get-started/quickstart/fork-a-repo - +Consider creating a `fork `_ +of the repository if you want to eventually push a contribution to the official +PyAnsys repository. For additional information, see :ref: dev_practices. Licensing --------- - All contributed code will be licensed under the MIT License found in the repository. If you did not write the code yourself, it is your responsibility to ensure that the existing license is compatible and included in the contributed files. You must obtain permission from the original author to relicense the code. -See :ref:`license_file` for more details. +See :ref:`license_file` for more information.