From a05841de9573a211ba7a5855831a673dc9623982 Mon Sep 17 00:00:00 2001 From: Luca Marconato Date: Sat, 4 Jan 2025 01:27:59 +0100 Subject: [PATCH] improved release process and its documentation --- .github/release.yml | 22 +++ .github/workflows/release.yml | 54 ++---- CHANGELOG.md | 201 --------------------- docs/changelog.md | 4 + docs/contributing.md | 202 +-------------------- docs/index.md | 1 + docs/template_usage.md | 326 ---------------------------------- 7 files changed, 45 insertions(+), 765 deletions(-) create mode 100644 .github/release.yml delete mode 100644 CHANGELOG.md create mode 100644 docs/changelog.md delete mode 100644 docs/template_usage.md diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 00000000..c8880edd --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,22 @@ +changelog: + exclude: + labels: + - release-ignore + authors: + - pre-commit-ci + categories: + - title: Major + labels: + - "release-major" + - title: Minor + labels: + - "release-minor" + - title: Changed + labels: + - "release-changed" + - title: Fixed + labels: + - "release-fixed" + - title: Other Changes + labels: + - "*" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d4a3c816..276fd4d4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,50 +1,30 @@ name: Release on: - push: - # Sequence of patterns matched against refs/tags - tags: - - "v*" # Push events to matching v*, i.e. v1.0, v20.15.10 - pull_request: - paths: - - .github/workflows/release.yml + release: + types: [published] jobs: - release: - # requires that you have put your twine API key in your - # github secrets (see readme for details) + build-and-inspect-package: + name: Build & inspect package. runs-on: ubuntu-latest - permissions: - contents: write + if: startsWith(github.ref, 'refs/tags/v') steps: - uses: actions/checkout@v4 - with: - fetch-depth: 0 - uses: hynek/build-and-inspect-python-package@v2 - id: build_dist - - name: determine tag - run: echo "tag=${GITHUB_REF/refs\/tags\/v/}" >> "$GITHUB_ENV" - - name: debug dist - run: | - set -x - echo "dist=${{ steps.build_dist.outputs.dist }}" - ls -l ${{ steps.build_dist.outputs.dist }} - mkdir -p dist - cp ${{ steps.build_dist.outputs.dist }}/*.whl ./dist/ - cp ${{ steps.build_dist.outputs.dist }}/*.gz ./dist/ - - name: Create Release - uses: "softprops/action-gh-release@v2" - if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') + upload-to-pypi: + name: Upload package to PyPI + needs: build-and-inspect-package + runs-on: ubuntu-latest + if: startsWith(github.ref, 'refs/tags/v') + + steps: + - name: Download built artifact to dist/ + uses: actions/download-artifact@v4 with: - tag_name: ${{ github.ref }} - name: ${{ env.tag }} - draft: false - prerelease: ${{ contains(env.tag, 'rc') || contains(env.tag, 'a') || contains(env.tag, 'b') }} - target_commitish: ${{ github.sha }} - files: dist/* - - name: Publish PyPI Package - if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') - uses: pypa/gh-action-pypi-publish@release/v1 + name: Packages + path: dist + - uses: pypa/gh-action-pypi-publish@release/v1 with: password: ${{ secrets.TWINE_API_KEY }} diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 4c517d67..00000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,201 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog][], -and this project adheres to [Semantic Versioning][]. - -[keep a changelog]: https://keepachangelog.com/en/1.0.0/ -[semantic versioning]: https://semver.org/spec/v2.0.0.html - -## incoming release - -- Global setting variables for showing circles as points and point size for scatter widget #309 #334 -- Sorting the element names and coordinate system names alphabetically #285 - -## [0.5.4] - 2024-11-26 - -### Changed - -- Support for `xarray.DataTree` (which moved from `datatree.DataTree`) - -### Added - -- CLI interface from spatialdata branch -- New function to get layer by name #315 @minhtien-trinh -- New annotation function to display text near polygons #315 @minhtien-trinh - -### Fixed - -- Bug wrong radii transformed circles (e.g. with Visium lowres) #318 -- Bugs: instance id shifted by 1; obsm visualization; background color for labels #320 -- Bug adjusting contrast limit for RGB data #276 - -## [0.5.3] - 2024-09-25 - -### Fixed - -- Bug table was not reset after an element without table was added #317 -- Bug when changing channel for a multichannel image #301 #302 -- Bug when plotting catgorical annotations on points #304 - -## [0.5.3] - 2024-08- - -### Added - -- New Scatter Widget based on PyQtGraph, replacing the previous Matplotlib-based widget. - - New Features: - - Separate color controls for continuous and discrete data: - - Continuous: Histogram of values, LUT adjustment, contrast control. - - Discrete: Scrollable legend, class color modification. - - Pseudohistogram plot for single-axis data. - - Highlight nearby data points under the cursor with dynamic status display. - - Expanded ROI annotations (lasso and rectangle tools) - - Multiple disjointed ROIs with modifiable options. - - Annotation name dialog for saving annotations. - -### Updated - -Documentation: Notebooks updated with the new Scatter Widget information and screenshots. - -## [0.5.2] - 2024-08-16 - -### Minor - -- Modernized release workflow - -## [0.5.1] - 2024-08-07 - -### Changed - -- RGB is now detected based on axis names in .c (pass `("r","g","b")` or - `("r","g","b", "a")`to c_coords argument when parsing the Image(2D / 3D)Model) - @aeisenbarth #153 - -## [0.5.0] - 2024-07-03 - -### Added - -- New annotation widget for managing shapes annotations @melonora #233 #261 -- Showing image channel names in var widget for easy channel selection #254 - -### Fixed - -- Fixed scatterplot widget #247 -- Fixed contrast limits for images #265 - -## [0.4.1] - 2024-03-30 - -### Fixed - -- Saving shapes and points with `Shift + E` now saves 2D data (a z dim was wrongly added) - -## [0.4.0] - 2024-03-24 - -### Added - -- Multi table support #199 @melonora -- Color shapes and points by values in dataframe in addition to tables #216 - -### Fixed - -- Avoid exception when registering shortcuts #201 @aeisenbarth -- Fix wrong point size when affine specified #193 -- Wrong element visiblity when changing coordinate system #207 -- Cleaned up data model #180 -- Fixes correct matching of geometies and annoations via join #208 -- Better docstrings #219 - -## [0.3.1] - 2023-11-11 - -### Fix - -- removed npe (napari plugin engine) dependency - -## [0.3.0] - 2023-11-09 - -### Added - -- New APIs for changing coordinate systems #169 -- New APIs for adding single elements #170 -- Improved code to link new layers to layers with a `SpatialData` object #173 - -### Fixed - -- Enabled saving annotations #168 -- Added safeguard when table is None #177 @aeisenbarth -- Fix plotting annotations when changing element #175 -- Fixed installation requirements #185 @goanpeca - -## [0.2.8] - 2023-10-30 - -### Added - -- Global parameters POINT_THRESHOLD and POLYGON_THRESHOLD added to allow users to adjust these parameters. - -### Fixed - -- Updated dependencies -- Updated installation instructions since napari conda-forge no longer installs Qt backend. @psobolewskiPhD -- Allow for viewing SpatialData object with no annotations. @aeisenbarth - -## [0.2.7] - 2023-10-02 - -### Added - -- Multiple SpatialData objects support (ported from the "spatialdata" branch) -- Interactive is more ergonomic, has a headless parameter, can be used to display pre-configured elements -- Remembering user layer visibility settings when changing coordinate system - -### Fixed - -- Fixes in CLI -- Several internal bugfixes and code refactorings -- Fixes in updating affine transformation when changing coordinate system - -## [0.2.6] - 2023-07-13 - -### Fixed - -- Wrong tag preventing the release to pip (the previous tag was not of a commit merged to main). - -## [0.2.5] - 2023-07-13 - -### Fixed - -- CLI @berombau @LucaMarconato -- Display of points and circles @LucaMarconato -- Issue with name reinitialization @tothmarcella -- Reverted to use PyQt5 @melonora -- RGB/RGBA correctly displayed for 3/4 channel images @rahulbshrestha -- Layer visibility changes when changing coordinate system @melonora -- Performance with multiscale images @LucaMarconato -- Refactored internal code to prepare for future refactoring @melonora - -### Thanks - -- Reviewers @giovp @timtreis @kevinyamauchi and the users that reported bugs. - -## [0.2.4] - 2023-05-23 - -### Added - -- Color circles and polygons with annotations (#73) - -## [0.2.3] - 2023-05-11 - -### Fixed - -- Shapes support - -## [0.2.1] - 2023-05-04 - -### Fixed - -- Package versioning (#63) - -## [0.2.0] - 2023-05-04 - -### Merged - -- Merge pull request #62 from scverse/kevinyamauchi-patch-1 - Install spatialdata from pypi diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 00000000..22146453 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,4 @@ +# Changelog + +Please refer directly to the [Releases](https://github.com/scverse/napari-spatialdata/releases) section on GitHub, where you can find curated release notes for each release. +For developers, please consult the [contributing guide](https://github.com/scverse/spatialdata/blob/main/docs/contributing.md), which explains how to keep release notes are up-to-date at each release. diff --git a/docs/contributing.md b/docs/contributing.md index 84d015f8..1ee0da05 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,203 +1,3 @@ # Contributing guide -Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this repo, too. -This document will not reproduce the entire content from there. Instead, it aims at summarizing the most important -information to get you started on contributing. - -We assume that you are already familiar with git and with making pull requests on GitHub. If not, please refer -to the [scanpy developer guide][]. - -## Installing dev dependencies - -In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build -the documentation_. It's easy to install them using `pip`: - -```bash -cd cookiecutter-scverse-instance -pip install -e ".[dev,test,doc]" -``` - -## Code-style - -This template uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either -automatically fix issues with the code, or raise an error message. See [pre-commit checks](template_usage.md#pre-commit-checks) for -a full list of checks enabled for this repository. - -To enable pre-commit locally, simply run - -```bash -pre-commit install -``` - -in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time. - -Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. If you didn't run `pre-commit` before -pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message. - -If pre-commit.ci added a commit on a branch you still have been working on locally, simply use - -```bash -git pull --rebase -``` - -to integrate the changes into yours. -While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage. - -Finally, most editors have an _autoformat on save_ feature. Consider enabling this option for [black][black-editors] -and [prettier][prettier-editors]. - -[black-editors]: https://black.readthedocs.io/en/stable/integrations/editors.html -[prettier-editors]: https://prettier.io/docs/en/editors.html - -## Writing tests - -```{note} -Remember to first install the package with `pip install '-e[dev,test]'` -``` - -This package uses the [pytest][] for automated testing. Please [write tests][scanpy-test-docs] for every function added -to the package. - -Most IDEs integrate with pytest and provide a GUI to run tests. Alternatively, you can run all tests from the -command line by executing - -```bash -pytest -``` - -in the root of the repository. Continuous integration will automatically run the tests on all pull requests. - -[scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests - -## Publishing a release - -### Updating the version number - -Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief - -> Given a version number MAJOR.MINOR.PATCH, increment the: -> -> 1. MAJOR version when you make incompatible API changes, -> 2. MINOR version when you add functionality in a backwards compatible manner, and -> 3. PATCH version when you make backwards compatible bug fixes. -> -> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. - -We use [bump2version][] to automatically update the version number in all places and automatically create a git tag. -Run one of the following commands in the root of the repository - -```bash -bump2version patch -bump2version minor -bump2version major -``` - -Once you are done, run - -``` -git push --tags -``` - -to publish the created tag on GitHub. - -[bump2version]: https://github.com/c4urself/bump2version - -### Building and publishing the package on PyPI - -Python packages are not distributed as source code, but as _distributions_. The most common distribution format is the so-called _wheel_. To build a _wheel_, run - -```bash -python -m build -``` - -This command creates a _source archive_ and a _wheel_, which are required for publishing your package to [PyPI][]. These files are created directly in the root of the repository. - -Before uploading them to [PyPI][] you can check that your _distribution_ is valid by running: - -```bash -twine check dist/* -``` - -and finally publishing it with: - -```bash -twine upload dist/* -``` - -Provide your username and password when requested and then go check out your package on [PyPI][]! - -For more information, follow the [Python packaging tutorial][]. - -It is possible to automate this with GitHub actions, see also [this feature request][pypi-feature-request] -in the cookiecutter-scverse template. - -[python packaging tutorial]: https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives -[pypi-feature-request]: https://github.com/scverse/cookiecutter-scverse/issues/88 - -## Writing documentation - -Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features: - -- the [myst][] extension allows to write documentation in markdown/Markedly Structured Text -- [Numpy-style docstrings][numpydoc] (through the [napoloen][numpydoc-napoleon] extension). -- Jupyter notebooks as tutorials through [myst-nb][] (See [Tutorials with myst-nb](#tutorials-with-myst-nb-and-jupyter-notebooks)) -- [Sphinx autodoc typehints][], to automatically reference annotated input and output types - -See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information -on how to write documentation. - -### Tutorials with myst-nb and jupyter notebooks - -The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [myst-nb][]. -Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells. -It is your reponsibility to update and re-run the notebook whenever necessary. - -If you are interested in automatically running notebooks as part of the continuous integration, please check -out [this feature request](https://github.com/scverse/cookiecutter-scverse/issues/40) in the `cookiecutter-scverse` -repository. - -#### Hints - -- If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. Only - if you do so can sphinx automatically create a link to the external documentation. -- If building the documentation fails because of a missing link that is outside your control, you can add an entry to - the `nitpick_ignore` list in `docs/conf.py` - -#### Building the docs locally - -```bash -cd docs -make html -open _build/html/index.html -``` - -or use [sphinx-autobuild](https://sphinx-extensions.readthedocs.io/en/latest/sphinx-autobuild.html) - -```bash -sphinx-autobuild docs docs/_build/html -``` - - - -[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html -[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html -[github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui -[codecov]: https://about.codecov.io/sign-up/ -[codecov docs]: https://docs.codecov.com/docs -[codecov bot]: https://docs.codecov.com/docs/team-bot -[codecov app]: https://github.com/apps/codecov -[pre-commit.ci]: https://pre-commit.ci/ -[readthedocs.org]: https://readthedocs.org/ -[myst-nb]: https://myst-nb.readthedocs.io/en/latest/ -[jupytext]: https://jupytext.readthedocs.io/en/latest/ -[pre-commit]: https://pre-commit.com/ -[anndata]: https://github.com/scverse/anndata -[mudata]: https://github.com/scverse/mudata -[pytest]: https://docs.pytest.org/ -[semver]: https://semver.org/ -[sphinx]: https://www.sphinx-doc.org/en/master/ -[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html -[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html -[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html -[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints -[pypi]: https://pypi.org/ +Please refer to the [contribution guide from the `spatialdata` repository](https://github.com/scverse/spatialdata/blob/main/docs/contributing.md). diff --git a/docs/index.md b/docs/index.md index 79a6fdb6..87c21cec 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,6 +10,7 @@ api.md cli.md contributing.md limitations.md +changelog.md references.md ``` diff --git a/docs/template_usage.md b/docs/template_usage.md deleted file mode 100644 index 1a0ebd29..00000000 --- a/docs/template_usage.md +++ /dev/null @@ -1,326 +0,0 @@ ---- -orphan: true ---- - -# Using this template - -Welcome to the developer guidelines! This document is split into two parts: - -1. The [repository setup](#setting-up-the-repository). This section is relevant primarily for the repository maintainer and shows how to connect - continuous integration services and documents initial set-up of the repository. -2. The [contributor guide](contributing.md#contributing-guide). It contains information relevant to all developers who want to make a contribution. - -## Setting up the repository - -### First commit - -If you are reading this, you should have just completed the repository creation with : - -```bash -cruft create https://github.com/scverse/cookiecutter-scverse -``` - -and you should have - -``` -cd cookiecutter-scverse-instance -``` - -into the new project directory. Now that you have created a new repository locally, the first step is to push it to github. To do this, you'd have to create a **new repository** on github. -You can follow the instructions directly on [github quickstart guide][]. -Since `cruft` already populated the local repository of your project with all the necessary files, we suggest to _NOT_ initialize the repository with a `README.md` file or `.gitignore`, because you might encounter git conflicts on your first push. -If you are familiar with git and knows how to handle git conflicts, you can go ahead with your preferred choice. - -:::{note} -If you are looking at this document in the [cookiecutter-scverse-instance][] repository documentation, throughout this document the name of the project is `cookiecutter-scverse-instance`. Otherwise it should be replaced by your new project name: `cookiecutter-scverse-instance`. -::: - -Now that your new project repository has been created on github at `https://github.com/scverse/cookiecutter-scverse-instance` you can push your first commit to github. -To do this, simply follow the instructions on your github repository page or a more verbose walkthrough here: - -Assuming you are in `/your/path/to/cookiecutter-scverse-instance`. Add all files and commit. - -```bash -# stage all files of your new repo -git add --all -# commit -git commit -m "first commit" -``` - -You'll notice that the command `git commit` installed a bunch of packages and triggered their execution: those are pre-commit! To read more about what they are and what they do, you can go to the related section [Pre-commit checks](#pre-commit-checks) in this document. - -:::{note} -There is a chance that `git commit -m "first commit"` fails due to the `prettier` pre-commit formatting the file `.cruft.json`. No problem, you have just experienced what pre-commit checks do in action. Just go ahead and re-add the modified file and try to commit again: - -```bash - git add -u # update all tracked file - git commit -m "first commit" -``` - -::: - -Now that all the files of the newly created project have been committed, go ahead with the remaining steps: - -```bash -# update the `origin` of your local repo with the remote github link -git remote add origin https://github.com/scverse/cookiecutter-scverse-instance.git -# rename the default branch to main -git branch -M main -# push all your files to remote -git push -u origin main -``` - -Your project should be now available at `https://github.com/scverse/cookiecutter-scverse-instance`. While the repository at this point can be directly used, there are few remaining steps that needs to be done in order to achieve full functionality. - -### Coverage tests with _Codecov_ - -Coverage tells what fraction of the code is "covered" by unit tests, thereby encouraging contributors to -[write tests](contributing.md#writing-tests). -To enable coverage checks, head over to [codecov][] and sign in with your GitHub account. -You'll find more information in "getting started" section of the [codecov docs][]. - -In the `Actions` tab of your projects' github repository, you can see that the workflows are failing due to the **Upload coverage** step. The error message in the workflow should display something like: - -``` -... - Retrying 5/5 in 2s.. - {'detail': ErrorDetail(string='Could not find a repository, try using repo upload token', code='not_found')} -Error: 404 Client Error: Not Found for url: -... -``` - -While [codecov docs][] has a very extensive documentation on how to get started, _if_ you are using the default settings of this template we can assume that you are using [codecov][] in a github action workflow and hence you can make use of the [codecov bot][]. - -To set it up, simply go to the [codecov app][] page and follow the instructions to activate it for your repository. -Once the activation is completed, go back to the `Actions` tab and re-run the failing workflows. - -The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/scverse/cookiecutter-scverse-instance`. You might have to wait couple of minutes and the coverage of this repository should be ~60%. - -If your repository is private, you will have to specify an additional token in the repository secrets. In brief, you need to: - -1. Generate a Codecov Token by clicking _setup repo_ in the codecov dashboard. - - If you have already set up codecov in the repository by following the previous steps, you can directly go to the codecov repo webpage. -2. Go to _Settings_ and copy **only** the token `_______-____-...`. -3. Go to _Settings_ of your newly created repository on GitHub. -4. Go to _Security > Secrets > Actions_. -5. Create new repository secret with name `CODECOV_TOKEN` and paste the token generated by codecov. -6. Past these additional lines in `/.github/workflows.test.yaml` under the **Upload coverage** step: - ```bash - - name: Upload coverage - uses: codecov/codecov-action@v3 - with: - token: ${{ secrets.CODECOV_TOKEN }} - ``` -7. Go back to github `Actions` page an re-run previously failed jobs. - -### Documentation on _readthedocs_ - -We recommend using [readthedocs.org][] (RTD) to build and host the documentation for your project. -To enable readthedocs, head over to [their website][readthedocs.org] and sign in with your GitHub account. -On the RTD dashboard choose "Import a Project" and follow the instructions to add your repository. - -- Make sure to choose the correct name of the default branch. On GitHub, the name of the default branch should be `main` (it has - recently changed from `master` to `main`). -- We recommend to enable documentation builds for pull requests (PRs). This ensures that a PR doesn't introduce changes - that break the documentation. To do so, got to `Admin -> Advanced Settings`, check the - `Build pull requests for this projects` option, and click `Save`. For more information, please refer to - the [official RTD documentation](https://docs.readthedocs.io/en/stable/pull-requests.html). -- If you find the RTD builds are failing, you can disable the `fail_on_warning` option in `.readthedocs.yaml`. - -If your project is private, there are ways to enable docs rendering on [readthedocs.org][] but it is more cumbersome and requires a different subscription for read the docs. See a guide [here](https://docs.readthedocs.io/en/stable/guides/importing-private-repositories.html). - -### Pre-commit checks - -[Pre-commit][] checks are fast programs that -check code for errors, inconsistencies and code styles, before the code -is committed. - -We recommend setting up [pre-commit.ci][] to enforce consistency checks on every commit -and pull-request. - -To do so, head over to [pre-commit.ci][] and click "Sign In With GitHub". Follow -the instructions to enable pre-commit.ci for your account or your organization. You -may choose to enable the service for an entire organization or on a per-repository basis. - -Once authorized, pre-commit.ci should automatically be activated. - -#### Overview of pre-commit hooks used by the template - -The following pre-commit checks are for code style and format: - -- [black](https://black.readthedocs.io/en/stable/): standard code - formatter in Python. -- [isort](https://pycqa.github.io/isort/): sort module imports into - sections and types. -- [prettier](https://prettier.io/docs/en/index.html): standard code - formatter for non-Python files (e.g. YAML). -- [blacken-docs](https://github.com/asottile/blacken-docs): black on - python code in docs. - -The following pre-commit checks are for errors and inconsistencies: - -- [flake8](https://flake8.pycqa.org/en/latest/): standard check for errors in Python files. - - [flake8-tidy-imports](https://github.com/adamchainz/flake8-tidy-imports): - tidy module imports. - - [flake8-docstrings](https://github.com/PyCQA/flake8-docstrings): - pydocstyle extension of flake8. - - [flake8-rst-docstrings](https://github.com/peterjc/e8-rst-docstrings): - extension of `flake8-docstrings` for `rst` docs. - - [flake8-comprehensions](https://github.com/adamchainz/e8-comprehensions): - write better list/set/dict comprehensions. - - [flake8-bugbear](https://github.com/PyCQA/flake8-bugbear): - find possible bugs and design issues in program. - - [flake8-blind-except](https://github.com/elijahandrews/flake8-blind-except): - checks for blind, catch-all `except` statements. -- [yesqa](https://github.com/asottile/yesqa): - remove unneccesary `# noqa` comments, follows additional dependencies listed above. -- [autoflake](https://github.com/PyCQA/autoflake): - remove unused imports and variables. -- [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks): generic pre-commit hooks. - - **detect-private-key**: checks for the existence of private keys. - - **check-ast**: check whether files parse as valid python. - - **end-of-file-fixer**:check files end in a newline and only a newline. - - **mixed-line-ending**: checks mixed line ending. - - **trailing-whitespace**: trims trailing whitespace. - - **check-case-conflict**: check files that would conflict with case-insensitive file systems. -- [pyupgrade](https://github.com/asottile/pyupgrade): - upgrade syntax for newer versions of the language. -- **forbid-to-commit**: Make sure that `*.rej` files cannot be commited. These files are created by the - [automated template sync](#automated-template-sync) if there's a merge conflict and need to be addressed manually. - -### How to disable or add pre-commit checks - -- To ignore lint warnigs from **flake8**, see [Ignore certain lint warnings](#how-to-ignore-certain-lint-warnings). -- You can add or remove pre-commit checks by simply deleting relevant lines in the `.pre-commit-config.yaml` file. - Some pre-commit checks have additional options that can be specified either in the `pyproject.toml` or tool-specific - config files, such as `.prettierrc.yml` for **prettier** and `.flake8` for **flake8**. - -### How to ignore certain lint warnings - -The [pre-commit checks](#pre-commit-checks) include [flake8](https://flake8.pycqa.org/en/latest/) which checks -for errors in Python files, including stylistic errors. - -In some cases it might overshoot and you may have good reasons to ignore certain warnings. - -To ignore an specific error on a per-case basis, you can add a comment `# noqa` to the offending line. You can also -specify the error ID to ignore, with e.g. `# noqa: E731`. Check the [flake8 guide][] for reference. - -Alternatively, you can disable certain error messages for the entire project. To do so, edit the `.flake8` -file in the root of the repository. Add one line per linting code you wish to ignore and don't forget to add a comment. - -```toml -... -# line break before a binary operator -> black does not adhere to PEP8 -W503 -# line break occured after a binary operator -> black does not adhere to PEP8 -W504 -... -``` - -[flake8 guide]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html - -### API design - -Scverse ecosystem packages should operate on [AnnData][] and/or [MuData][] data structures and typically use an API -as originally [introduced by scanpy][scanpy-api] with the following submodules: - -- `pp` for preprocessing -- `tl` for tools (that, compared to `pp` generate interpretable output, often associated with a corresponding plotting - function) -- `pl` for plotting functions - -You may add additional submodules as appropriate. While we encourage to follow a scanpy-like API for ecosystem packages, -there may also be good reasons to choose a different approach, e.g. using an object-oriented API. - -[scanpy-api]: https://scanpy.readthedocs.io/en/stable/usage-principles.html - -### Using VCS-based versioning - -By default, the template uses hard-coded version numbers that are set in `pyproject.toml` and [managed with -bump2version](contributing.md#publishing-a-release). If you prefer to have your project automatically infer version numbers from git -tags, it is straightforward to switch to vcs-based versioning using [hatch-vcs][]. - -In `pyproject.toml` add the following changes, and you are good to go! - -```diff ---- a/pyproject.toml -+++ b/pyproject.toml -@@ -1,11 +1,11 @@ - [build-system] - build-backend = "hatchling.build" --requires = ["hatchling"] -+requires = ["hatchling", "hatch-vcs"] - - - [project] - name = "cookiecutter-scverse-instance" --version = "0.3.1dev" -+dynamic = ["version"] - -@@ -60,6 +60,9 @@ -+[tool.hatch.version] -+source = "vcs" -+ - [tool.coverage.run] - source = ["cookiecutter-scverse-instance"] - omit = [ -``` - -Don't forget to update the [Making a release section](contributing.md#publishing-a-release) in this document accordingly, after you are done! - -[hatch-vcs]: https://pypi.org/project/hatch-vcs/ - -### Automated template sync - -Automated template sync is enabled by default. This means that every night, a GitHub action runs [cruft][] to check -if a new version of the `scverse-cookiecutter` template got released. If there are any new changes, a pull request -proposing these changes is created automatically. This helps keeping the repository up-to-date with the latest -coding standards. - -It may happen that a template sync results in a merge conflict. If this is the case a `*.ref` file with the -diff is created. You need to manually address these changes and remove the `.rej` file when you are done. -The pull request can only be merged after all `*.rej` files have been removed. - -:::{tip} -The following hints may be useful to work with the template sync: - -- GitHub automatically disables scheduled actions if there has been not activity to the repository for 60 days. - You can re-enable or manually trigger the sync by navigating to `Actions` -> `Sync Template` in your GitHub repository. -- If you want to ignore certain files from the template update, you can add them to the `[tool.cruft]` section in the - `pyproject.toml` file in the root of your repository. More details are described in the - [cruft documentation][cruft-update-project]. -- To disable the sync entirely, simply remove the file `.github/workflows/sync.yaml`. - -::: - -[cruft]: https://cruft.github.io/cruft/ -[cruft-update-project]: https://cruft.github.io/cruft/#updating-a-project - -## Moving forward - -You have reached the end of this document. Congratulations! You have successfully set up your project and are ready to start. -For everything else related to documentation, code style, testing and publishing your project ot pypi, please refer to the [contributing docs](contributing.md#contributing-guide). - - - -[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html -[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html -[github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui -[codecov]: https://about.codecov.io/sign-up/ -[codecov docs]: https://docs.codecov.com/docs -[codecov bot]: https://docs.codecov.com/docs/team-bot -[codecov app]: https://github.com/apps/codecov -[pre-commit.ci]: https://pre-commit.ci/ -[readthedocs.org]: https://readthedocs.org/ -[myst-nb]: https://myst-nb.readthedocs.io/en/latest/ -[jupytext]: https://jupytext.readthedocs.io/en/latest/ -[pre-commit]: https://pre-commit.com/ -[anndata]: https://github.com/scverse/anndata -[mudata]: https://github.com/scverse/mudata -[pytest]: https://docs.pytest.org/ -[semver]: https://semver.org/ -[sphinx]: https://www.sphinx-doc.org/en/master/ -[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html -[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html -[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html -[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints