From a8e5c64a016d45e3ca6cfb9923f4f13241c1f33e Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 19 Apr 2024 17:16:40 -0600 Subject: [PATCH 01/10] Move meet-up page under contributing --- docs/{work-with-us.md => contributing/our-meet-ups.md} | 0 mkdocs.yml | 6 ++++-- 2 files changed, 4 insertions(+), 2 deletions(-) rename docs/{work-with-us.md => contributing/our-meet-ups.md} (100%) diff --git a/docs/work-with-us.md b/docs/contributing/our-meet-ups.md similarity index 100% rename from docs/work-with-us.md rename to docs/contributing/our-meet-ups.md diff --git a/mkdocs.yml b/mkdocs.yml index 3dce0d64..9494e6bc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -48,8 +48,10 @@ plugins: nav: - Welcome: - "What is earthaccess?": "index.md" - - "Quick Start": "welcome/quick_start.md" - - "Work With Us": "work-with-us.md" + - "Quick start": "welcome/quick_start.md" + - "Work with us": + - "contributing/index.md" + - "Our meet-ups": "contributing/our-meet-ups.md" - "Resources": "resources.md" - User Guide: - "Overview": "user_guide/overview.md" From 71803e093dfc5ef166881ad8235713addc0d9774 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 19 Apr 2024 17:34:10 -0600 Subject: [PATCH 02/10] Split out development environment and releasing docs --- docs/contributing/development.md | 62 +++++++++++++++++++ docs/contributing/index.md | 102 ++----------------------------- docs/contributing/releasing.md | 28 +++++++++ 3 files changed, 95 insertions(+), 97 deletions(-) create mode 100644 docs/contributing/development.md create mode 100644 docs/contributing/releasing.md diff --git a/docs/contributing/development.md b/docs/contributing/development.md new file mode 100644 index 00000000..2cea2e8e --- /dev/null +++ b/docs/contributing/development.md @@ -0,0 +1,62 @@ +# Development environment setup + +1. Fork [nsidc/earthaccess](https://github.com/nsidc/earthaccess) +1. Clone your fork (`git clone git@github.com:{my-username}/earthaccess`) + +`earthaccess` uses Poetry to build and publish the package to PyPI, the defacto Python repository. In order to develop new features or fix bugs etc. we need to set up a virtual environment and install the library locally. We can accomplish this with Poetry and/or Conda. + +### Using Conda + +If we have `mamba` (or `conda`) installed, we can use the environment file included in the `ci` folder. This will install all the libraries we need (including Poetry) to start developing `earthaccess`: + +```bash +mamba env update -f ci/environment-dev.yml +mamba activate earthaccess-dev +poetry install +``` + +After activating our environment and installing the library with Poetry we can run Jupyter lab and start testing the local distribution or we can use `make` to run the tests and lint the code. +Now we can create a feature branch and push those changes to our fork! + +### Using Poetry + +If we want to use Poetry, first we need to [install it](https://python-poetry.org/docs/#installation). After installing Poetry we can use the same workflow we used for Conda, first we install the library locally: + +```bash +poetry install +``` + +and now we can run the local Jupyter Lab and run the scripts etc. using Poetry: + +```bash +poetry run jupyter lab +``` + +!!! note + + You may need to use `poetry run make ...` to run commands in the environment. + +### Managing Dependencies + +If you need to add a dependency, you should do the following: + +- Run `poetry add ` for a required (non-development) dependency +- Run `poetry add --group=dev ` for a development dependency, such + as a testing or code analysis dependency + +Both commands will add an entry to `pyproject.toml` with a version that is +compatible with the rest of the dependencies. However, `poetry` pins versions +with a caret (`^`), which is not what we want. Therefore, you must locate the +new entry in `pyproject.toml` and change the `^` to `>=`. (See +[poetry-relax](https://github.com/zanieb/poetry-relax) for the reasoning behind +this.) + +In addition, you must also add a corresponding entry to +`ci/environment-mindeps.yaml`. You'll notice in that file that required +dependencies should be pinned exactly to the versions specified in +`pyproject.toml` (after changing `^` to `>=` there), and that development +dependencies should be left unpinned. + +Finally, for _development dependencies only_, you must add an entry to +`ci/environment-dev.yaml` with the same version constraint as in +`pyproject.toml`. diff --git a/docs/contributing/index.md b/docs/contributing/index.md index e94ecec4..92babfbd 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,78 +1,15 @@ # Contributing When contributing to this repository, please first discuss the change you wish to make via issue, -email, or any other method with the owners of this repository before making a change. +email, or any other method with the maintainers before making a change. -Please note that we have a [code of conduct](./CODE_OF_CONDUCT.md). Please follow it in all of your interactions with the project. - -## Development environment - -1. Fork [nsidc/earthaccess](https://github.com/nsidc/earthaccess) -1. Clone your fork (`git clone git@github.com:{my-username}/earthaccess`) - -`earthaccess` uses Poetry to build and publish the package to PyPI, the defacto Python repository. In order to develop new features or fix bugs etc. we need to set up a virtual environment and install the library locally. We can accomplish this with Poetry and/or Conda. - -### Using Conda - -If we have `mamba` (or `conda`) installed, we can use the environment file included in the `ci` folder. This will install all the libraries we need (including Poetry) to start developing `earthaccess`: - -```bash -mamba env update -f ci/environment-dev.yml -mamba activate earthaccess-dev -poetry install -``` - -After activating our environment and installing the library with Poetry we can run Jupyter lab and start testing the local distribution or we can use `make` to run the tests and lint the code. -Now we can create a feature branch and push those changes to our fork! - -### Using Poetry - -If we want to use Poetry, first we need to [install it](https://python-poetry.org/docs/#installation). After installing Poetry we can use the same workflow we used for Conda, first we install the library locally: - -```bash -poetry install -``` - -and now we can run the local Jupyter Lab and run the scripts etc. using Poetry: - -```bash -poetry run jupyter lab -``` - -!!! note - - You may need to use `poetry run make ...` to run commands in the environment. - -### Managing Dependencies - -If you need to add a dependency, you should do the following: - -- Run `poetry add ` for a required (non-development) dependency -- Run `poetry add --group=dev ` for a development dependency, such - as a testing or code analysis dependency - -Both commands will add an entry to `pyproject.toml` with a version that is -compatible with the rest of the dependencies. However, `poetry` pins versions -with a caret (`^`), which is not what we want. Therefore, you must locate the -new entry in `pyproject.toml` and change the `^` to `>=`. (See -[poetry-relax](https://github.com/zanieb/poetry-relax) for the reasoning behind -this.) - -In addition, you must also add a corresponding entry to -`ci/environment-mindeps.yaml`. You'll notice in that file that required -dependencies should be pinned exactly to the versions specified in -`pyproject.toml` (after changing `^` to `>=` there), and that development -dependencies should be left unpinned. - -Finally, for _development dependencies only_, you must add an entry to -`ci/environment-dev.yaml` with the same version constraint as in -`pyproject.toml`. +Please note that we have a [code of conduct](/CODE_OF_CONDUCT.md). Please follow it in all of your interactions with the project. ## First Steps to contribute -- Read the documentation -- Fork this repo (see "Development environment" section above for more) -- Install environment (see "Development environment" section above for more) +- Read the documentation! +- Fork this repo and set up development environment (see + [development environment documentation](./development.md) for details) - Run the unit tests successfully in `main` branch: - `make test` @@ -144,32 +81,3 @@ the stubs appear under `stubs/cmr`. 1. You may merge the Pull Request once you have the sign-off of another developer, or if you do not have permission to do that, you may request the reviewer to merge it for you. - -## Release process - -> :memo: The versioning scheme we use is [SemVer](http://semver.org/). Note that until -> we agree we're ready for v1.0.0, we will not increment the major version. - -1. Ensure all desired features are merged to `main` branch and `CHANGELOG.md` is updated. -1. Use `bump-my-version` to increase the version number in all needed places, e.g. to - increase the minor version (`1.2.3` to `1.3.0`): - - ```plain - bump-my-version bump minor - ``` - -1. Push a tag on the new commit containing the version number, prefixed with `v`, e.g. - `v1.3.0`. -1. [Create a new GitHub Release](https://github.com/nsidc/earthaccess/releases/new). We - hand-curate our release notes to be valuable to humans. Please do not auto-generate - release notes and aim for consistency with the GitHub Release descriptions from other - releases. - -> :gear: After the GitHub release is published, multiple automations will trigger: -> -> - Zenodo will create a new DOI. -> - GitHub Actions will publish a PyPI release. - -> :memo: `earthaccess` is published to conda-forge through the -> [earthdata-feedstock](https://github.com/conda-forge/earthdata-feedstock), as this -> project was renamed early in its life. The conda package is named `earthaccess`. diff --git a/docs/contributing/releasing.md b/docs/contributing/releasing.md new file mode 100644 index 00000000..fe62a000 --- /dev/null +++ b/docs/contributing/releasing.md @@ -0,0 +1,28 @@ +# Release process + +> :memo: The versioning scheme we use is [SemVer](http://semver.org/). Note that until +> we agree we're ready for v1.0.0, we will not increment the major version. + +1. Ensure all desired features are merged to `main` branch and `CHANGELOG.md` is updated. +1. Use `bump-my-version` to increase the version number in all needed places, e.g. to + increase the minor version (`1.2.3` to `1.3.0`): + + ```plain + bump-my-version bump minor + ``` + +1. Push a tag on the new commit containing the version number, prefixed with `v`, e.g. + `v1.3.0`. +1. [Create a new GitHub Release](https://github.com/nsidc/earthaccess/releases/new). We + hand-curate our release notes to be valuable to humans. Please do not auto-generate + release notes and aim for consistency with the GitHub Release descriptions from other + releases. + +> :gear: After the GitHub release is published, multiple automations will trigger: +> +> - Zenodo will create a new DOI. +> - GitHub Actions will publish a PyPI release. + +> :memo: `earthaccess` is published to conda-forge through the +> [earthdata-feedstock](https://github.com/conda-forge/earthdata-feedstock), as this +> project was renamed early in its life. The conda package is named `earthaccess`. From e88695e14ce6292b5c7feb0bf2df3a74977b4dc7 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 19 Apr 2024 17:36:53 -0600 Subject: [PATCH 03/10] Enable navigation index pages --- mkdocs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 9494e6bc..a734f298 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,6 +16,10 @@ theme: toggle: icon: material/toggle-switch name: Switch to light mode + features: + # Allow navigation sections to link to index/overview pages. + # See: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages + - navigation.indexes repo_name: nsidc/earthaccess repo_url: https://github.com/nsidc/earthaccess From f7ab38bb6cc94b27d707dbe78493dbf9981ed756 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 19 Apr 2024 17:49:06 -0600 Subject: [PATCH 04/10] Un-nest pages from "Welcome" section --- README.md | 2 +- docs/{welcome/quick_start.md => quick-start.md} | 0 mkdocs.yml | 13 ++++++------- 3 files changed, 7 insertions(+), 8 deletions(-) rename docs/{welcome/quick_start.md => quick-start.md} (100%) diff --git a/README.md b/README.md index c2267df3..f0888a39 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ Try it in your browser without installing anything! [![Binder](https://mybinder. ## How to Get Started with `earthaccess` -Go to the [Quick Start](welcome/quick_start.md) to learn how to install and see a simple example of using `earthaccess`. +Go to the [Quick Start](quick-start.md) to learn how to install and see a simple example of using `earthaccess`. ## Compatibility diff --git a/docs/welcome/quick_start.md b/docs/quick-start.md similarity index 100% rename from docs/welcome/quick_start.md rename to docs/quick-start.md diff --git a/mkdocs.yml b/mkdocs.yml index a734f298..1e231d0b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,13 +50,12 @@ plugins: - "**/.ipynb_checkpoints/*" nav: - - Welcome: - - "What is earthaccess?": "index.md" - - "Quick start": "welcome/quick_start.md" - - "Work with us": - - "contributing/index.md" - - "Our meet-ups": "contributing/our-meet-ups.md" - - "Resources": "resources.md" + - "What is earthaccess?": "index.md" + - "Quick start": "quick-start.md" + - "Work with us": + - "contributing/index.md" + - "Our meet-ups": "contributing/our-meet-ups.md" + - "Resources": "resources.md" - User Guide: - "Overview": "user_guide/overview.md" - "Authentication": "user_guide/authenticate.md" From 632700de55f8ed78cdabe094494f61a72c5dc9ce Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 19 Apr 2024 18:17:54 -0600 Subject: [PATCH 05/10] Use navigation index functionality to remove a sub-nav from user guide --- docs/user_guide/{overview.md => index.md} | 0 mkdocs.yml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/user_guide/{overview.md => index.md} (100%) diff --git a/docs/user_guide/overview.md b/docs/user_guide/index.md similarity index 100% rename from docs/user_guide/overview.md rename to docs/user_guide/index.md diff --git a/mkdocs.yml b/mkdocs.yml index 1e231d0b..fd9c3331 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,7 +57,7 @@ nav: - "Our meet-ups": "contributing/our-meet-ups.md" - "Resources": "resources.md" - User Guide: - - "Overview": "user_guide/overview.md" + - "user_guide/index.md" - "Authentication": "user_guide/authenticate.md" - "Search": "user_guide/search.md" - "Access": "user_guide/access.md" From 975602c17165fd0d26c1c8163740e0a6e00a5b4f Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 24 Apr 2024 18:52:45 -0600 Subject: [PATCH 06/10] Clarify conda/poetry choice Co-authored-by: Andy Barrett --- docs/contributing/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 2cea2e8e..7425fcba 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -3,7 +3,7 @@ 1. Fork [nsidc/earthaccess](https://github.com/nsidc/earthaccess) 1. Clone your fork (`git clone git@github.com:{my-username}/earthaccess`) -`earthaccess` uses Poetry to build and publish the package to PyPI, the defacto Python repository. In order to develop new features or fix bugs etc. we need to set up a virtual environment and install the library locally. We can accomplish this with Poetry and/or Conda. +`earthaccess` uses Poetry to build and publish the package to PyPI, the defacto Python repository. In order to develop new features or fix bugs etc. we need to set up a virtual environment and install the library locally. We can accomplish this with Conda and Poetry, or just with Poetry. Both workflows achieve the same result. ### Using Conda From 0e21d1d9a2f249d374b3be86469452b8e810b3ec Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 24 Apr 2024 18:53:02 -0600 Subject: [PATCH 07/10] Apply suggested wording change Co-authored-by: Andy Barrett --- docs/contributing/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 7425fcba..954be7ae 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -38,7 +38,7 @@ poetry run jupyter lab ### Managing Dependencies -If you need to add a dependency, you should do the following: +If you need to add a new dependency, you should do the following: - Run `poetry add ` for a required (non-development) dependency - Run `poetry add --group=dev ` for a development dependency, such From 3b4e0017d8720d1dc678d3cf10d16374abf0e47e Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 24 Apr 2024 18:53:18 -0600 Subject: [PATCH 08/10] More concise wording Co-authored-by: Andy Barrett --- docs/contributing/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 954be7ae..c4ec122b 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -44,7 +44,7 @@ If you need to add a new dependency, you should do the following: - Run `poetry add --group=dev ` for a development dependency, such as a testing or code analysis dependency -Both commands will add an entry to `pyproject.toml` with a version that is +Both commands add an entry to `pyproject.toml` with a version that is compatible with the rest of the dependencies. However, `poetry` pins versions with a caret (`^`), which is not what we want. Therefore, you must locate the new entry in `pyproject.toml` and change the `^` to `>=`. (See From e76456c9300080fb4ed55659ec48c3e4ebc3dfb7 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 24 Apr 2024 18:53:30 -0600 Subject: [PATCH 09/10] Clarify wording Co-authored-by: Andy Barrett --- docs/contributing/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/development.md b/docs/contributing/development.md index c4ec122b..0350329f 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -52,7 +52,7 @@ new entry in `pyproject.toml` and change the `^` to `>=`. (See this.) In addition, you must also add a corresponding entry to -`ci/environment-mindeps.yaml`. You'll notice in that file that required +`ci/environment-mindeps.yaml`. You'll notice in this file that required dependencies should be pinned exactly to the versions specified in `pyproject.toml` (after changing `^` to `>=` there), and that development dependencies should be left unpinned. From 8a4e2a0ceee3d5826ecfc3262b43cb9d5eb285d2 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 24 Apr 2024 18:58:14 -0600 Subject: [PATCH 10/10] Improve intro text to contributing docs --- docs/contributing/index.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 92babfbd..50a606b9 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,7 +1,10 @@ # Contributing -When contributing to this repository, please first discuss the change you wish to make via issue, -email, or any other method with the maintainers before making a change. +When contributing to this repository, please first discuss the change you wish to make +with the community and maintainers via +[a GitHub issue](https://github.com/nsidc/earthaccess/issues), +[a GitHub Discussion](https://github.com/nsidc/earthaccess/discussions), +or [any other method](our-meet-ups.md). Please note that we have a [code of conduct](/CODE_OF_CONDUCT.md). Please follow it in all of your interactions with the project.