.. _contributing:
Contributing
============
Before contributing to a PyAnsys library, you must understand the general
coding paradigms used for PyAnsys development.
#. 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 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,
class, or method, following :ref:`Numpydoc docstrings` as specified by
PyAnsys :ref:`Documentation style`. 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 function, class, or method has a reasonable coverage (greater
than 80%). For information on automated testing, see :ref:`Testing`.
#. Do not include any datasets for which a license is not available
or commercial use is prohibited.
#. Review the Ansys `Contributor Code of Conduct
`_.
All PyAnsys projects are hosted on `GitHub`_ in the form of :ref:`Git`
repositories. GitHub is a platform that not only provides storage for
projects but also additional features like code reviews or issue boards.
.. raw:: html
Create a GitHub account
-----------------------
To use GitHub, start by creating an account for the platform. Follow the
`GitHub Join Process `_.
For Ansys employees who would like to join the Ansys GitHub organization,
visit `Join Ansys GitHub Organization `_.
.. _github_repo_sections:
Interact with GitHub repository sections
----------------------------------------
Once you have a GitHub account and access to the Ansys GitHub organization,
you are able to interact with the different repositories. While each
repository contains all tabbed sections in the following list,
your access level determines which tabbed sections you can see.
.. figure:: images/github_sections.png
:alt: GitHub repository sections
:align: center
* ``Code``: Tree view of the project's structure
* ``Issues``: Posts noting issues or requesting new features
* ``Pull requests``: Code changes either awaiting review or merging or already closed
* ``Discussions``: Exchanges about development practices with project maintainers
* ``Actions``: Available CI/CD workflows
* ``Projects``: Plans for organizing and developing the repository
* ``Wiki``: Basic project information
* ``Security``: Configurations related to security issues, vulnerabilities, and alerts
* ``Insights``: General information about the repository and its contributors
* ``Settings``: Configurations for access and integration with third-party tools
Create an issue
---------------
You create an issue to report a bug, request a new feature, or ask for library-specific
help. You can comment on an issue to interact with other users, developers, and project
maintainers.
To open an issue, select the ``Issues`` tab in the :ref:`github_repo_sections` and click
``New Issue``. Then, select a template for the type of issue to open.
GitHub issues require the usage of Markdown files instead of ReStructuredText (RST)
files. For more information, see `Basic writing and formatting syntax
`_
in the GitHub documentation.
Report bugs
~~~~~~~~~~~
If you encounter a bug in the code, open a new issue and select the template
for creating a bug report. In the bug report, take these actions:
- Indicate the operating system, Python version, and library version that you are using.
- Include a small piece of code to allow others to reproduce the bug that you found.
- Add any additional information that you consider useful for fixing the bug.
Request new features
~~~~~~~~~~~~~~~~~~~~
If you would like a new feature to be added to a PyAnsys library, open a
new issue and select either the template for code enhancements or a
feature idea. In the issue, take these actions:
- Describe the main goal of the feature that you'd like to have added and why it is beneficial
to the project.
- Describe how this feature might possibly be implemented and the steps that should be
followed.
- Add any references that could help during the development process.
Fork a repository
-----------------
Forking a repository is like copying and pasting a project into your own GitHub
profile. Notice that only repositories labeled as ``public`` can be forked. You
cannot fork a repository labeled as ``internal`` or ``private``.
To fork a repository, click the **Fork** button at the top of the project's
**Code** page.
Clone a repository
------------------
Cloning a repository means downloading it to your local machine. While there are two ways of
doing this (``HTTPS`` or ``SSH``), to force the usage of ``SSH``, only this method is explained.
Clone using SSH
~~~~~~~~~~~~~~~
Cloning using ``SSH`` requires that SSH be enabled. For more information, see :ref:`Enable SSH`.
To clone a repository using SSH, run this command:
.. code-block:: bash
git clone git@github.com:/.git
For example, clone the `PyMAPDL`_ project with this command:
.. code-block:: bash
git clone git@github.com:ansys/pymapdl.git
Install a library in editable mode
----------------------------------
You can install a Python library in *editable mode*, which
lets you modify the source code and have these new changes
reflected in your Python environment.
To install a Python library in editable mode:
1. Ensure that you :ref:`Create` and :ref:`Activate` a Python virtual environment,
as explained in the :ref:`Virtual environments` section.
2. Update ``pip`` with this command:
.. code-block:: bash
python -m pip install --upgrade pip
3. Install the library with this command:
.. code-block:: bash
python -m pip install --editable .
Create a branch
---------------
It is likely that the repository's default branch name is ``main`` or ``master``. This is the
development branch for PyAnsys projects. For more information, see :ref:`Branching model`.
You must implement new contributions in a different branch and then :ref:`Create a pull request`
so that these changes can later be merged into the repository's ``main`` branch.
To create a branch, run this command:
.. code-block:: bash
git checkout -b
.. _branch_naming:
Branch-naming conventions
~~~~~~~~~~~~~~~~~~~~~~~~~
The following requirements for naming branches helps to streamline
development. They help core developers know what kind of
changes any given branch is introducing before looking at the code.
- ``fix/``: Bug fixes, patches, or experimental changes that are
minor.
- ``feat/``: Changes that introduce a new feature or significant
addition.
- ``junk/``: Experimental changes that can be deleted if they go
stale.
- ``maint/``: General maintenance of the repository or CI routines.
- ``docs/``: Changes pertaining only to documentation.
- ``no-ci/``: Low-impact activity that should not trigger CI
routines.
- ``testing/`` or ``test/``: Improvements or changes to testing.
- ``release/``: Releases (see below).
Push your branch
----------------
Once you have implemented new changes and committed them, push your
branch with this command:
.. code-block:: bash
git push -u origin
Your changes are upload to the repository, but they are only visible in the branch
that you just pushed.
Create a pull request
---------------------
Once you have tested your branch locally, create a pull request (PR) and target your merge to
the repository's ``main`` branch. This automatically runs CI testing and verifies that your changes
work across all supported platforms. For procedural information, see `Creating a pull request
`_
in the GitHub documentation.
After you submit your PR, a project maintainer reviews your code to verify that it meets
the :ref:`Packaging style`, :ref:`Coding style`, and :ref:`Documentation style`.
Once your code is approved, if you have write permission, you can merge the PR
and then delete the PR branch. If you don't have write permission, the reviewer
or someone else with write permission must merge your PR and then delete your PR branch.
.. admonition:: Always delete your PR branch after merging it into the main branch.
You can set up automatic deletion of branches in **Settings > General > Pull Requests**.
Commit-naming conventions
~~~~~~~~~~~~~~~~~~~~~~~~~
Following the `conventional commits standards `_,
helps to streamline development and improve the :ref:`Changelog `
quality. Here is a list of the most common commit types:
- ``fix:``: Bug fixes.
- ``feat:``: Changes that introduce a new feature or significant addition.
- ``docs:``: Changes pertaining only to documentation.
- ``style:``: Changes that do not affect the meaning of the code (white-space,
formatting, missing semi-colons, etc.).
- ``refactor:``: A code change that neither fixes a bug nor adds a feature.
- ``perf:``: A code change that improves performance.
- ``test:``: Improvements or changes to testing.
- ``build:``: Changes that affect the build system or external dependencies
(example scopes: pip, npm, make).
- ``ci:``: Changes to the CICD configuration files and scripts.
- ``chore:``: Other changes that don't modify the code (example scopes: release,
versioning, etc.).
- ``revert:``: Reverts a previous commit.
Use GitHub CLI
--------------
Because developers do not like leaving their terminals when working in projects,
GitHub offers a `command-line interface (CLI) `_.
This program lets you interact with most of the features available in the
web version of GitHub. For available commands, see the
`GitHub CLI `_ documentation.