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/contributing/development.md b/docs/contributing/development.md new file mode 100644 index 00000000..0350329f --- /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 Conda and Poetry, or just with Poetry. Both workflows achieve the same result. + +### 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 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 + as a testing or code analysis dependency + +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 +[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 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. + +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..50a606b9 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,78 +1,18 @@ # 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. +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. - -## 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 +84,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/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/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`. 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/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 3dce0d64..fd9c3331 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 @@ -46,13 +50,14 @@ plugins: - "**/.ipynb_checkpoints/*" nav: - - Welcome: - - "What is earthaccess?": "index.md" - - "Quick Start": "welcome/quick_start.md" - - "Work With Us": "work-with-us.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" + - "user_guide/index.md" - "Authentication": "user_guide/authenticate.md" - "Search": "user_guide/search.md" - "Access": "user_guide/access.md"