Joss edits

.github/workflows/ci.yml

@@ -37,14 +37,15 @@ jobs:
         with:
           extra_args: --hook-stage manual --all-files
       - name: Run PyLint
-        run: |
-          echo "::add-matcher::$GITHUB_WORKSPACE/.github/matchers/pylint.json"
-          pipx run nox -s pylint
+        run: pipx run nox -s pylint -- --output-format=github
 
   # Run tests and upload to codecov
   test:
     name: Check Python ${{ matrix.python-version }} on ${{ matrix.runs-on }}
     runs-on: ${{ matrix.runs-on }}
+    if: |
+      ${{!startsWith(github.event.head_commit.message, 'docs:') }} ||
+      ${{!startsWith(github.event.head_commit.message, 'style:') }}
     needs: [pre-commit]
     strategy:
       # Otherwise, the workflow would stop if a single job fails. We want to
@@ -53,11 +54,10 @@ jobs:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
         runs-on: [ubuntu-latest, macos-latest, windows-latest]
-
     env:
       FORCE_COLOR: 3
       NUMBA_DISABLE_JIT: "1"
-
+    timeout-minutes: 30
     steps:
       # Checkout current git repository
       - name: Checkout
@@ -68,33 +68,33 @@ jobs:
       - name: Switch to Current Branch
         run: git checkout ${{ env.BRANCH }}
 
-      # Install Mambaforge with conda-forge dependencies
-      - name: Setup Mambaforge
-        uses: conda-incubator/setup-miniconda@v3
+      - name: Get current week number of year
+        id: date
+        run: echo "date=$(date +%Y-W%W)" >> $GITHUB_OUTPUT # e.g., 2024-W19
+
+      # Install Micromamba with conda-forge dependencies
+      - name: Setup Micromamba
+        uses: mamba-org/setup-micromamba@v1
         with:
-          activate-environment: polartoolkit
           environment-file: env/testing_env.yml
-          python-version: ${{ matrix.python-version }}
-          channels: conda-forge,nodefaults
-          channel-priority: strict
-          miniforge-version: latest
-          miniforge-variant: Mambaforge
-          mamba-version: "*"
-          use-mamba: true
-          auto-activate-base: false
-
-      # Install the package in editable mode
-      - name: Install local package
-        run: pip install -e .
+          create-args: >-
+            python=${{ matrix.python-version }}
+          post-cleanup: "all"
+          cache-downloads: false
+          # environment cache is persistent for one week.
+          cache-environment-key:
+            micromamba-environment-${{ steps.date.outputs.date }}
 
-        # Show installed pkg information for postmortem diagnostic
-      - name: List installed packages
-        run: mamba list
+      # Install the package that we want to test
+      - name: Install the package
+        run: pip install --no-deps -e .
 
       - name: Run the tests
         run: >-
-          pytest -m "not earthdata and not issue" -ra --cov --cov-report=xml
+          pytest -m "not fetch and not issue" -ra --cov --cov-report=xml
           --cov-report=term --durations=20
 
       - name: Upload coverage report
         uses: codecov/[email protected]
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.pre-commit-config.yaml

@@ -1,14 +1,19 @@
 ci:
   autoupdate_commit_msg: "chore: update pre-commit hooks"
   autofix_commit_msg: "style: pre-commit fixes"
+  autoupdate_schedule: quarterly
 
 exclude: |
   (?x)^(
       docs/index.md|
+      docs/install.md|
+      docs/citing.md|
+      docs/overview.md|
+      docs/reference.md|
       docs/api/polartoolkit.rst|
       docs/api/polartoolkit.fetch.rst|
       docs/api/polartoolkit.maps.rst|
-      docs/api/polartoolkit.profile.rst|
+      docs/api/polartoolkit.profiles.rst|
       docs/api/polartoolkit.regions.rst|
       docs/api/polartoolkit.utils.rst|
       docs/_polartoolkit_refs.bib|
@@ -17,8 +22,8 @@ exclude: |
       .github/ISSUE_TEMPLATE/feature_request.md|
       .github/config.yml|
       CONTRIBUTING.md|
-      binder/environment.yml|
       templates/CHANGELOG.md.j2|
+      README.md|
   )$
 
 repos:
@@ -34,7 +39,7 @@ repos:
         additional_dependencies: [black==23.7.0]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.1.6"
+    rev: "v0.4.2"
     hooks:
       - id: ruff
         args: ["--fix", "--show-fixes"]
@@ -44,6 +49,7 @@ repos:
     rev: "v4.5.0"
     hooks:
       - id: check-added-large-files
+        exclude: ^docs/datasets/
       - id: check-case-conflict
       - id: check-merge-conflict
       - id: check-symlinks

CONTRIBUTING.md

@@ -3,7 +3,7 @@
 
 <sub>Adapted from the great contribution guidelines of the [Fatiando a Terra](https://www.fatiando.org/) packages<sub>.
 
-> This document contains some general guidlines to help with contributing to this code. Contributing to a package can be a daunting task, if you want help please reach out on the [GitHub discussions page](https://github.com/mdtanker/polartoolkit/discussions)!
+> This document contains some general guidelines to help with contributing to this code. Contributing to a package can be a daunting task, if you want help please reach out on the [GitHub discussions page](https://github.com/mdtanker/polartoolkit/discussions)!
 
 Any kind of help would be much appreciated. Here are a few ways to contribute:
 * 🐛 Submitting bug reports and feature requests
@@ -40,7 +40,9 @@ contributions.
   - [Code Review](#code-review)
 * [Publish a new release](#publish-a-new-release)
 * [Update the Dependencies](#update-the-dependencies)
+* [Create a conda environment file](#create-a-conda-environment-file)
 * [Set up Binder](#set-up-the-binder-configuration)
+* [Release Checklist](#release-checklist)
 
 ## What Can I Do?
 
@@ -215,12 +217,14 @@ Leave a comment in the PR and we'll help you out.
 
 The Docs are build with `Sphinx` and `Read the Docs`. Due to the above mentioned issues with the included C programs, `Read the Docs (RTD)` can't run the scripts which are part of the docs (i.e. the gallery examples). Because of this the notebooks don't execute on a build, as specified by `execute_notebooks: 'off'` in `_config.yml`. Here is how to run/update the docs on your local machine.
 
-> **Note:** The docs are automatically built on PR's by `RTD`, but it's good practise to build them manually before a PR, to check them for errors.
+> **Note:** The docs are automatically built on PR's by `RTD`, but it's good practice to build them manually before a PR, to check them for errors.
 
 #### Run all .ipynb's to update them
 
     make run_doc_files
 
+If your edits haven't changed any part of the core package, then there is no need to re-run the notebooks. If you changed a notebook, just clear it's contents and re-run that one notebook.
+
 #### Check the build manually (optional)
 
 You can build the docs using, but this will require pandoc to be install on your machine:
@@ -239,14 +243,9 @@ nox -s docs -- --serve
 
 Add, commit, and push all changes to GitHub in a Pull Request, and `RTD` should automatically build the docs.
 
-In each PR, you will see section of the checks for RTD. Click on this to preview the docs for the PR.
+In each PR, you will see section of the checks for `RTD`. Click on this to preview the docs for the PR.
 
-RTD uses the conda environment specified in `env/RTD_env.yml` when it's building.
-To create or update this file based on the necessary dependencies in [docs] of `pyproject.toml`, run the following command:
-
-```
-make RTD_env
-```
+`RTD` uses the conda environment specified in `env/RTD_env.yml` when it's building.
 
 ### Code Review
 
@@ -279,83 +278,48 @@ If you have any trouble, leave a comment in the PR or
 
 This will almost always be done by the developers, but as a guide for them, here are instructions on how to release a new version of the package.
 
-Follow all the above instructions for formating and building the docs
+Follow all the above instructions for formatting. Push your changes to a new or existing Pull Request. Once the automated GitHub Actions run (and pass), merge the PR into the main branch.
 
 ### PyPI (pip)
-Manually increment the version in polartoolkit/__init__.py:
-
-  version = "X.Y.Z"
-
-Build the package locally into the /dist folder:
-
-  make build
-
-Upload the dist files to Test PyPI:
-
-    make test_publish
-
-This should automatically find the TestPyPI username and token from a `.pypirc` file in your home directory.
-
-Make a new environment and activate it:
-
-    make test_pypi_env
-    mamba activate polartoolkit_test_pypi
-
- and run the following, replacing the asterisks with the version number:
-
-    pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ polartoolkit==******
-
-Run a few gallery examples to make sure this env works, then its ready to publish to the real PyPI:
-
-    make publish
-
-Now push the changes to GitHub and make a release with the matching version number.
+PyPI release are made automatically via GitHub actions whenever a pull request is merged.
 
 ### Conda-Forge
-Once the new version is on PyPI, we can update the conda-forge feedstock.
-
-Fork the [conda-forge polartoolkit feedstock](https://github.com/conda-forge/polartoolkit-feedstock) on github:
-
-Clone the fork and checkout a new branch
-
-    git clone https://github.com/mdtanker/polartoolkit-feedstock
-
-    git checkout -b update
-
-Update the `meta.yaml` with the new PyPI version with `grayskull`
-
-  grayskull pypi polartoolkit
-
-Copy the new contents into the old `meta.yaml` file.
-
-Push the changes to GitHub
-
-    git add .
-
-    git commit -m "updating polartoolkit"
-
-    git push origin update
-
-Open a PR on GitHub with the new branch.
+Once the new version is on PyPI, within a few hours a bot will automatically open a new PR in the [PolarToolkit conda-forge feedstock](https://github.com/conda-forge/polartoolkit-feedstock). Go through the checklist on the PR. Most of the time the only actions needs are updated any changes made to the dependencies since the last release. Merge the PR and the new version will be available on conda-forge shortly.
 
 Once the new version is on conda, update the binder .yml file, as below.
 
 ## Update the dependencies
 
 To add or update a dependencies, add it to `pyproject.toml` either under `dependencies` or `optional-dependencies`. This will be included in the next build uploaded to PyPI.
 
-After release a new version on PyPI, we will create a new release on conda-forge, and the new dependencies should automatically be included there.
+If you add a dependency necessary for using the package, make sure to add it to the Binder config file and update the `environment.yml` file in the repository. See below.
 
-If you add a dependency necessary for using the package, make sure to add it to `env/env_test.ylm` and include it in the Binder config file. See below.
+## Create a conda environment file
 
-## Set up the binder configuration
+As a backup options for users experiencing install issues, we include a `environment.yml` file in the repo, which users can download and install from. To update this, run the following commands:
+
+```
+make remove
+make conda_install
+```
 
-To run this package online, Read the Docs will automatically create a Binder instance based on the configuration file `/binder/environment.yml`. This file reflects the latest release on Conda-Forge. Update it with the following commands.
+## Set up the binder configuration
 
-    make conda_install
+To run this package online, Read the Docs will automatically create a Binder instance based on the configuration file `environment.yml` in a separate repository [`Polartoolkit-Binder`](https://github.com/mdtanker/polartoolkit-binder). This file should reflect the latest release on Conda-Forge. To allow all optional features in Binder, we need to manually add optional dependencies to the `environment.yml` file. Also, to use the latest version of PolarToolkit within Binder, makes sure to update its version in the file after each release.
 
-    conda activate polartoolkit
+Once updated, rebuild the Binder environment, look at which package versions Binder used for each specified dependency, and update the environment file with these versions.
 
-    make binder_env
+Now, when submitting a PR, RTD will automatically build the docs and update the Binder environment.
 
-Now, when submitting a PR, RTD will automatically build the docs and update the Binder environment.
+## Release Checklist
+* re-run any relevant notebooks
+* check docs are building correctly using the GitHub actions link within the PR
+* merge the  PR
+* wait for `PyPI` to publish the new version [here](https://pypi.python.org/pypi/polartoolkit)
+* wait for a PR to be opened in the [feedstock](https://github.com/conda-forge/polartoolkit-feedstock)
+* update any changed dependencies in the feedstock PR and merge
+* wait for `conda` to publish the new version [here](https://anaconda.org/conda-forge/polartoolkit)
+* update backup `env/environment.yml`
+* update polartoolkit version in `environment.yml` in [PolarToolkit-Binder repo](https://github.com/mdtanker/polartoolkit-binder/blob/main/environment.yml)
+* test `PyPI` version with `make install_test` and `make test`
+* test `conda` version with `make conda_install` and `make test`