This project borrows from the LINCC Frameworks' template of best practices for python code organization, testing, and automation. It is meant to help new RAIL projects use the same standards, and be interoperable with other packages in the RAIL-iverse.
Notable differences from the original template include:
- support for namespaced packages
- remove sphinx documentation generation
- keep pylint configuration in the pyproject.toml (instead of creating pylint.rc files)
Copier is required to use this template. Copier is an open source tool that hydrates projects from templates and natively supports updating projects as the original template matures.
Our template works best with Copier v8.0 and above.
Choose where you would like to create your new project, and call copier with the template.
>$ copier copy gh:LSSTDESC/RAIL-project-template <path/to/destination>
<Answer the questions>
>$ git init
>$ pip install -e .[dev]
After you've created a project with this template and pushed it to GitHub, a small amount of additional set up in the repository will allow you to take full advantage of the features that the template offers.
The Continuous Integration tests built into the template will automatically generate the code coverage files that Codecov needs for reporting. All you need to do is enable Codecov for your repository.
Go here: https://github.com/apps/codecov and configure it for your repository
A GitHub action has been created that will automatically publish a package to PyPI. To make use of that, you'll use "trusted publishing". For a high level overview of trusted publishing see the PyPI documentation here: https://docs.pypi.org/trusted-publishers/
For specific instructions to set up trusted publishing between GitHub and PyPI, take a look at the PyPI documentation here: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
To easily track issues across many repositories, we can make use of GitHub's projects. A GitHub action is included in template that will automatically add new issues to the primary RAIL project tracker, however, you'll need to setup a Person Access Token and save it as repository secret for it to work.
These instructions explain how to create a Personal Access Token: https://github.com/actions/add-to-project#creating-a-pat-and-adding-it-to-your-repository
Once your token is created save it as a repository secret with the name: ADD_TO_PROJECT_PAT.
Pre-commit runs various tests against your code. These checks are mostly the same as those that are run in continuous integration, but by running them locally it's possible to reduce the amount of time between committing and finding errors in the code.
It is not required to use pre-commit if you use this template, but it is available
if you would like. To enable it, simply run pre-commit install.
When creating a pull request in this fork, make sure to set the
base repository to LSSTDESC/RAIL-project-template (it will
default to the upstream of lincc-frameworks:main).
See full documentation at LINCC's readthedocs