CONTRIBUTING.md

{{PROJECT_NAME}}

Development and Contributing Guidelines

Table of Contents

1. Contributing
• Commit Messages
2. Project Dependencies
3. Tests
4. Linting and Type Hinting
5. Documentation
6. Continuous Integration
• Further useful information on the workflows

Contributing

1. Fork the Project.
2. Create your Feature Branch (git checkout -b feature_name).
3. Commit your Changes (git commit -a -m "feat: a wonderful new feature").
4. Push to the Branch (git push origin feature_name).
5. Open a Pull Request.

Commit Messages:

This project (optionally) uses Python Semantic Release. To use this feature, please follow the commit message convention to ensure changes are correctly versioned in any future releases.

Cheat sheet:

• Patch release, backwards-compatible bug fix in git commit message title.
  • git commit -a -m "fix: a great fix"
• Minor release, backwards-compatible feat in git commit message title.
  • git commit -a -m "feat: a wonderful new feature"
• Major release, incompatible API change BREAKING CHANGE in git commit message footer (use fix or feat for message title).
  • git commit -a -m "feat: total refactor" -m "BREAKING CHANGE: breaks api"

(back to top)

Project Dependencies

Update to reflect the new project's specific requirements!

The below instructions assume a virtual environment created from mayapy is being used for the project, for more info see: https://help.autodesk.com/view/MAYACRE/ENU/?guid=GUID-6AF99E9C-1473-481E-A144-357577A53717.

Project dependencies are available in the requirements.in file, which should be compiled with pip-tools.

1. Install pip-tools:

   pip install pip-tools

2. Dependencies can be added to:
   • requirements.in: User requirements.
   • requirements-dev.in: Development requirements.
   • requirements-test.in: Test requirements.
3. Compile the requirement files as needed (below combines all three files into one requirements.txt, however it's possible to have separate files for each):

   pip-compile --output-file requirements.txt requirements.in requirements-dev.in requirements-test.in

4. Install dependencies:
   • Windows:

     • pip-sync --python-executable %VIRTUAL_ENV%/scripts/python.exe requirements.txt

   • Linux:

     • pip-sync --python-executable $VIRTUAL_ENV/bin/python.exe requirements.txt

(back to top)

Tests

Tests are written with Pytest and should adhere to the "Arrange, Act, Assert" pattern.

To run tests locally:

• pytest

with coverage:

• pytest --cov=src/

(back to top)

Linting and Type Hinting

Static code analysis is performed with Pylint, formatting with Black format, and type hinting with mypy.

To run pylint locally:

• pylint --rcfile=.pylintrc src/

  • A modified .pylintrc file is provided with modifications to ignore Maya import errors. Append to this file as needed.

Black formater can be run locally with:

• black src/

Run mypy checks locally with:

• mypy src/

  • A modified mypy.ini file is included with modifications to ignore Maya import errors. Append to this file as needed.

(back to top)

Documentation

Documentation is built with mkdocs. To build the docs locally:

• mkdocs build

To serve the docs locally:

• mkdocs serve

(back to top)

Continuous Integration

Continuous integration is set up with GitHub Actions, workflows can be found in the .github/workflows directory. There are 2 main workflows:

1. ci-main.yml: This workflow is intended to be a fast check to ensure the code is in a good state, and code standards are met. It runs automatically on every push and pull request to main or can be triggered from the Run workflow button on the actions menu. It runs tests (if they exist), and performs linting, formatting, and type hinting checks.
   
2. ci-release.yml: This workflow will do all the above, create a release version of the repo and deploy the documentation to GitHub pages. It can be run from the Run workflow button on the actions menu.
   

Further useful information on the workflows:

• Versions of Maya to test against can be specified in the reusable-maya-tests.yml file.
  • The Maya tests workflow will only run if tests exist in the tests directory, otherwise the CI will skip this workflow to avoid pulling the Maya Docker image unnecessarily.
• Coding standards enforced with pylint, black, and mypy, with minimal configuration.
• Docs are built with mkdocs and deployed to GitHub pages: https://{{PROJECT_OWNER}}.github.io/{{PROJECT_NAME}}.

  • To enable GitHub pages, go to the settings of your repository, scroll down to the GitHub Pages section, and select the gh-pages branch as the source. *

(back to top)