diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f4cb76a..6f59aa9 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,3 +1,3 @@ # automatically requests pull request reviews for files matching the given pattern; the last match takes precendence -* @sosey \ No newline at end of file +* @sosey @Roman-Supernova-PIT/software-admins \ No newline at end of file diff --git a/.github/workflows/dependabot.yml b/.github/workflows/dependabot.yml index 4a85006..fde1be6 100644 --- a/.github/workflows/dependabot.yml +++ b/.github/workflows/dependabot.yml @@ -1,3 +1,4 @@ +name: "Dependabot Checks" version: 2 updates: @@ -9,7 +10,7 @@ updates: interval: weekly open-pull-requests-limit: 10 reviewers: - - "sosey" + - "Roman-Supernova-PIT/software-admins" allow: - dependency-type: direct - dependency-type: indirect diff --git a/.github/workflows/sphinx-deploy.yml b/.github/workflows/sphinx-deploy.yml index 29534b6..8366e26 100644 --- a/.github/workflows/sphinx-deploy.yml +++ b/.github/workflows/sphinx-deploy.yml @@ -1,4 +1,4 @@ -name: "Deploy Sphinx documentation to Pages" +name: "Deploy Sphinx Package Documentation to Pages" on: push: diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index e0c40c5..1d0838c 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -12,7 +12,7 @@ concurrency: jobs: test: - uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1 + uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@924441154cf3053034c6513d5e06c69d262fb9a6 # v1.13.0 with: envs: | - linux: py311-test diff --git a/README.rst b/README.rst index 7780777..398d921 100644 --- a/README.rst +++ b/README.rst @@ -2,3 +2,42 @@ Roman Supernova PIT Packaging Guide =================================== The `Roman Supernova PIT Python Packaging Guide `__ is based on the OpenAstronomy package and contains an embedded `cookiecutter `__ template. + + +Using the Template +================== + +With this template and guide is a `cookiecutter `__ template which allows you to get started quickly with a package as described in this guide. + +To create a new package based on the template run: + +.. code-block:: console + + $ pip install cookiecutter cruft + $ cruft create https://github.com/Roman-Supernova-PIT/package-template + +and go through the steps offered in the cli naming your package and filling in your details. +Cruft is built on cookiecutter, and enables the updating of the template from the source. +This takes the form of pull requests to the repository that the new package is pushed to. +If a package already has a cookiecutter template, it can be linked to the parent repository using ``cruft link url-to-template``. + +To manually check whether the current environment matches with the template then ``cruft check`` will tell you what the current status is. +``cruft update`` will manually trigger an updating of the package to the template. + +If you would like to stick to simply the cookiecutter approach, the template still supports that functionality thusly: + +.. code-block:: console + + $ pip install cookiecutter + $ cookiecutter gh:Roman-Supernova-PIT/package-template -o ./output_directory + +This will create a new directory in your current directory named the same as the value of "packagename" you supplied. +Change into this directory and run ``git init`` to make it into a git repository, and make an initial commit. +This is required in order to have software versioning working for your package. + +The goal of the template is to quickly get you setup with the files described in the guide. +The template currently implements the following optional flags, all of which default to off: + +* ``include_example_code``: This option will fill your new package with some example functions to allow you to test it. +* ``use_compiled_extensions``: This turns on the features needed to support compiled extensions as described in :ref:`extensions`. +* ``enable_dynamic_dev_versions``: This enables a feature which ensures that ``my_package.__version__`` always returns the current git version as calculated by ``setuptools_scm`` when the package is installed as an editable install. See :ref:`dev-versions` for more details. diff --git a/docs/_static/logo_black_filled.png b/docs/_static/logo_black_filled.png new file mode 100644 index 0000000..494e0ba Binary files /dev/null and b/docs/_static/logo_black_filled.png differ diff --git a/docs/advanced/versioning.rst b/docs/advanced/versioning.rst index 37f0fc9..a6cbcd8 100644 --- a/docs/advanced/versioning.rst +++ b/docs/advanced/versioning.rst @@ -10,7 +10,8 @@ complex. We strongly recommend using `setuptools_scm `__ to do this. With a little effort and understanding it is possible to make the git history the single source of truth for all your version information, for your releases -and any development installs. +and any development installs. Using setuptools_scm is part of the default choices in the package +template and will be active unless you choose otherwise. .. _setuptools-scm: diff --git a/docs/ci.rst b/docs/ci.rst index bc9e7b4..db879af 100644 --- a/docs/ci.rst +++ b/docs/ci.rst @@ -11,7 +11,8 @@ Workflows can be set to begin on triggers for example, a ``git push`` or a new t There are an array solutions for running CI, Open Astronomy recommends `GitHub Actions `__ for projects using GitHub. GitHub Actions workflows are defined in the ``.github/workflows/`` folder at the root of the repo. -Open Astronomy maintains a `set of tools `__ to make configuring GitHub Actions easier. +Open Astronomy maintains a `set of tools `__ to make configuring GitHub Actions easier. A `free course `__ for GitHub Actions is available. + Examples ++++++++ diff --git a/docs/conf.py b/docs/conf.py index e20abba..3f7d63a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,6 +54,25 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] master_doc = 'index' + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = "alabaster" +html_static_path = ['_static'] +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + ] +} +html_theme_options = { + 'fixed_sidebar': True, + 'logo': "logo_black_filled.png", + 'logo_text_align': "left", + 'sidebar_width':'250px', + 'show_relbars':True, +} diff --git a/docs/minimal.rst b/docs/minimal.rst index 59b5ca6..fcb7b70 100644 --- a/docs/minimal.rst +++ b/docs/minimal.rst @@ -26,13 +26,12 @@ these files in turn. Assuming that you are planning to make your package open source, the most important file you will need to add to your package is an open source license. Many packages in the scientific Python ecosystem use the `3-clause BSD license -`_ and we recommend following -this or using the `MIT license `_ -unless you have a good reason not to. +`_ and the packages maintained by +the Roman Supernova PIT group will too. If you have a good reason not to, please +contact one of the software admins for the PIT. -To include the license in your package, create a file called LICENSE -and paste the license text into it, making sure that you update the -copyright year, authors, and any other required fields +The BSD 3-Clause license is included as part of the package template and will +be created when you generate a new package. .. _readme: @@ -44,8 +43,7 @@ what the package is, and either gives some information about how to install/use it or links to more extensive documentation. We recommend using the `reStructuredText (rst) `_ format for your README as this will ensure that the README gets rendered well online, e.g. -on `GitHub `_ or `GitLab `_ and on `PyPI -`_. +on `GitHub `_ or `PyPI `_. .. _package_init: diff --git a/{{ cookiecutter.package_name }}/.github/CODEOWNERS b/{{ cookiecutter.package_name }}/.github/CODEOWNERS index b2cbb99..4722111 100644 --- a/{{ cookiecutter.package_name }}/.github/CODEOWNERS +++ b/{{ cookiecutter.package_name }}/.github/CODEOWNERS @@ -1,3 +1,3 @@ # automatically requests pull request reviews for files matching the given pattern; the last match takes precendence -* @{{ cookiecutter.github_username }} \ No newline at end of file +* @{{ cookiecutter.github_username }} @Roman-Supernova-Pit/software-admins \ No newline at end of file diff --git a/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE.md b/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index a7ffec9..0000000 --- a/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,15 +0,0 @@ -* {{ cookiecutter.package_name }} version: -* Python version: -* Operating System: - -### Description - -Describe what you were trying to get done. -Tell us what happened, what went wrong, and what you expected to happen. - -### What I Did - -``` -Paste the command(s) you ran and the output. -If there was a crash, please include the traceback here. -``` \ No newline at end of file diff --git a/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md new file mode 100644 index 0000000..13c6dac --- /dev/null +++ b/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md @@ -0,0 +1,21 @@ +--- +name: "Feature request" +about: Suggest an idea for this project +title: "[New Feature]: " +labels: enhancement, needs triage +assignees: '' +--- + +## Is your feature request related to a problem? Please describe. + + +## Describe the solution you'd like + + +## Describe alternatives you've considered + + +## Additional context + + diff --git a/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md b/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..1b53dab --- /dev/null +++ b/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md @@ -0,0 +1,47 @@ +--- +name: "🐞 Issue report for {{ cookiecutter.package_name }}" +about: Create a report describing unexpected or incorrect behavior. +title: "[Issue]: " +labels: bug +assignees: '' +--- + +<!-- +Thanks for taking the time to fill out this report! +Please have a search on our repository to see if a similar +issue has already been posted. If a similar issue is closed, have a +quick look to see if you are satisfied by the resolution. + +If not please go ahead and open an issue! +--> + +### Current Behavior: +<!-- A concise description of what you're experiencing. --> + +### Expected Behavior: +<!-- A concise description of what you expected to happen. --> + +### Steps To Reproduce: +<!-- +Example: steps to reproduce the behavior: +1. In this environment... +1. With this config... +1. Run '...' +1. See error... +--> + +### Environment: +<!-- +Example: +- OS: Ubuntu 20.04 +- Node: 13.14.0 +- npm: 7.6.3 +- python: 3.13 +- numpy: 2.0 +--> + +### Anything else: +<!-- +Links? References? Anything that will give us more context about the issue that you are encountering! +--> + diff --git a/{{ cookiecutter.package_name }}/.github/PR_TEMPLATE.md b/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/PR_TEMPLATE.md similarity index 54% rename from {{ cookiecutter.package_name }}/.github/PR_TEMPLATE.md rename to {{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/PR_TEMPLATE.md index d865dce..203d54d 100644 --- a/{{ cookiecutter.package_name }}/.github/PR_TEMPLATE.md +++ b/{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/PR_TEMPLATE.md @@ -1,20 +1,39 @@ -<!-- If this PR closes a GitHub issue, reference it here by its number --> -Closes # +--- +name: "Pull Request for {{ cookiecutter.package_name }}" +about: Create a pull request to submit new or updated code to the repository +title: "[PR]: " +labels: possible solution +assignees: '' +--- +## What type of PR is this? (check all applicable) + +- [ ] Refactor +- [ ] Feature +- [ ] Bug Fix +- [ ] Optimization +- [ ] Documentation Update +- [ ] Have you followed the guidelines in our Contributing document? +- [ ] Have you checked to ensure there aren't other open [Pull Requests](../../../pulls) for the same update/change? <!-- describe the changes included with this PR here --> This PR addresses ... +<!-- If this PR closes a GitHub issue, reference it here by its number --> +Closes # + + <!-- if you can't perform these tasks due to permissions, please ask a maintainer to do them --> ## Tasks - [ ] **request a review from someone specific**, to avoid making the maintainers review every PR - [ ] Does this PR change user-facing code / API? (if not, label with `no-changelog-entry-needed`) - - [ ] write news fragment(s) in `changes/`: `echo "changed something" > changes/<PR#>.<changetype>.rst` (see below for change types) + - [ ] write news fragment(s) in `changes/`: `echo "changed something" > changes/<PR#>.<changetype>.rst` (see expansion below for change types) - [ ] update or add relevant tests - [ ] update relevant docstrings and / or `docs/` page - [ ] Do truth files need to be updated? + <details><summary>news fragment change types...</summary> - ``changes/<PR#>.general.rst``: infrastructure or miscellaneous change -- ``changes/<PR#>.docs.rst`` +- ``changes/<PR#>.docs.rst``: updates for documentation </details> \ No newline at end of file diff --git a/{{ cookiecutter.package_name }}/.github/workflows/labeler.yml b/{{ cookiecutter.package_name }}/.github/workflows/labeler.yml index 2d7a8b9..d58675e 100644 --- a/{{ cookiecutter.package_name }}/.github/workflows/labeler.yml +++ b/{{ cookiecutter.package_name }}/.github/workflows/labeler.yml @@ -27,7 +27,7 @@ documentation: - 'docs/**/*' - '*.md' - '.readthedocs.yaml' - - 'LICENSE' + - 'licenses/LICENSE.rst' installation: - changed-files: diff --git a/{{ cookiecutter.package_name }}/CONTRIBUTING.md b/{{ cookiecutter.package_name }}/CONTRIBUTING.md new file mode 100644 index 0000000..46b9bba --- /dev/null +++ b/{{ cookiecutter.package_name }}/CONTRIBUTING.md @@ -0,0 +1,163 @@ +Contributing to {{ cookiecutter.package_name }} +================================================ + +Reporting Issues +---------------- + +When opening an issue to report a problem, please try to provide a minimal code +example that reproduces the issue along with details of the operating +system and the Python, NumPy, and `{{ cookiecutter.package_name }}` versions you are using. + +Contributing Code and Documentation +----------------------------------- + +So you are interested in contributing to the {{ cookiecutter.package_name }} Project? Excellent! +We love contributions! We are open source, built on open source, and +we'd love to have you hang out in our community. + + +Anti Imposter Syndrome Reassurance +---------------------------------- + +We want your help. No, really. + +There may be a little voice inside your head that is telling you that you're not +ready to be an open source contributor; that your skills aren't nearly good +enough to contribute. What could you possibly offer a project like this one? + +We assure you - the little voice in your head is wrong. If you can write code or +documentation, you can contribute code to open source. +Contributing to open source projects is a fantastic way to advance one's coding +and open source workflow skills. Writing perfect code isn't the measure of a good +developer (that would disqualify all of us!); it's trying to create something, +making mistakes, and learning from those mistakes. That's how we all improve, +and we are happy to help others learn. + +Being an open source contributor doesn't just mean writing code, either. You can +help out by writing documentation, tests, or even giving feedback about the +project (and yes - that includes giving feedback about the contribution +process). Some of these contributions may be the most valuable to the project as +a whole, because you're coming to the project with fresh eyes, so you can see +the errors and assumptions that seasoned contributors have glossed over. + +Note: This text was originally written by +[Adrienne Lowe](https://github.com/adriennefriend) for a +[PyCon talk](https://www.youtube.com/watch?v=6Uj746j9Heo), and was adapted by +Astropy based on its use in the README file for the +[MetPy project](https://github.com/Unidata/MetPy). + + +How to Contribute, Best Practices +--------------------------------- + +Most contributions are done via [pull +requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) +from GitHub users' forks of {{ cookiecutter.package_name }} If you are new to this +style of development, you will want to read over our development workflow in the docs. + +When you open a pull request (which should be opened against the ``main`` +branch, not against any of the other branches), please make sure to +include the following: + +- **Code**: the code you are adding, which should follow + our coding guidelines + +- **Tests**: these are usually tests to ensure code that previously + failed now works (regression tests), or tests that cover as much as possible + of the new functionality to make sure it does not break in the future and + also returns consistent results on all platforms (since we run these tests on + many platforms/configurations). For more information about how to write + tests, see our testing guidelines. + +- **Documentation**: if you are adding new functionality, be sure to include a + description in the main documentation (in ``docs/``). + + +- **Performance improvements**: if you are making changes that impact package + performance, consider adding a reference for the performance benchmark + + + If you are opening a pull request you may not know + the PR number yet, but you can add it once the pull request is open. + + + +Checklist for Contributed Code +------------------------------ + +Before being merged, a pull request for a new feature will be reviewed to see if +it meets the following requirements. If you are unsure about how to meet all of these +requirements, please submit the PR and ask for help and/or guidance. + +**Scientific Quality** (when applicable) + * Is the submission relevant to astronomy? + * Are references included to the origin source for the algorithm? + * Does the code perform as expected? + * Has the code been tested against previously existing implementations? + +**Code Quality** + * Are the coding guidelines followed? + * Is the code compatible with the supported versions of Python? + * Are there dependencies other than the run-time dependencies listed in pyproject.toml? + * Is the package importable even if the C-extensions are not built? + * Are additional dependencies handled appropriately? + * Do functions that require additional dependencies raise an `ImportError` + if they are not present? + +**Testing** + * Are the testing guidelines followed? + * Are the inputs to the functions sufficiently tested? + * Are there tests for any exceptions raised? + * Are there tests for the expected performance? + * Are the sources for the tests documented? + * Have tests that require an optional dependency been marked as such? + * Does ``tox -e test`` run without failures? + +**Documentation** + * Are the documentation guidelines followed? + * Is there a docstring in [numpydoc format](https://numpydoc.readthedocs.io/en/latest/format.html) in the function describing: + * What the code does? + * The format of the inputs of the function? + * The format of the outputs of the function? + * References to the original algorithms? + * Any exceptions which are raised? + * An example of running the code? + * Is there any information needed to be added to the docs to describe the + function? + * Does the documentation build without errors or warnings? + +**License** + * Are there any conflicts with this code and existing codes? + +**Package requirements** + * Do all the GitHub Actions tests pass? If not, are they allowed to fail? + * If applicable, has an entry been added into the changelog? + * Can you check out the pull request and repeat the examples and tests? + +Other Tips +---------- + +- Behind the scenes, we conduct a number of tests or checks with new pull requests. + To prevent the automated tests from running, you can add ``[ci skip]`` + to your commit message. This is useful if your PR is a work in progress (WIP) and + you are not yet ready for the tests to run. For example: + + $ git commit -m "WIP widget [ci skip]" + + - If you already made the commit without including this string, you can edit + your existing commit message by running: + + $ git commit --amend + +- If your commit makes substantial changes to the documentation but none of + those changes include code snippets, then you can use ``[ci skip]``, + which will skip all CI except where the documentation is built. + +- When contributing trivial documentation fixes (i.e., fixes to typos, spelling, + grammar) that don't contain any special markup and are not associated with + code changes, please include the string ``[ci skip]`` in your commit + message. + + $ git commit -m "Fixed typo [ci skip]" + +- ``[ci skip]`` and ``[skip ci]`` are the same and can be used interchangeably. \ No newline at end of file diff --git a/{{ cookiecutter.package_name }}/pyproject.toml b/{{ cookiecutter.package_name }}/pyproject.toml index 87a12dc..fea36f3 100644 --- a/{{ cookiecutter.package_name }}/pyproject.toml +++ b/{{ cookiecutter.package_name }}/pyproject.toml @@ -46,7 +46,8 @@ docs = [ "matplotlib", "sphinx", "sphinx-automodapi", - "tomli" + "tomli", + "graphviz" ] {%- if cookiecutter.project_url %}