Toolkit to manipulate Earth observations and models.
Project description
terrapyn
Toolkit to manipulate Earth observations and models.
- Free software: BSD-3-Clause
- Documentation: https://colinahill.github.io/terrapyn.
Setup
Turn the project directory into a local Git repository
First, move into the package directory:
cd project-name/
Then, install the poetry dependency manager:
pip install poetry && poetry install
For more info on poetry, see python-poetry.org.
Lastly, make the directory a Git repository:
git init
Link the local repository to a remote repository
Create a remote repository on GitHub for this project with the following steps:
- Go to create new repository on GitHub.com.
- Fill in the repository name (
project-name
from above) and description. - Choose a Public or Private repo.
- Leave all other boxes unchecked.
Copy the URL of the repo and set it as the origin
remote:
git remote add origin https://gitlab.com/<username>/<project-name>.git
Install pre-commit so we perform checks before committing files
poetry run pre-commit install
Add the files and stage them for commitment
git add .
git commit -m "initial commit"
Name the current branch to main:
git branch -M main
Finally, push the initial commit to GitHub:
git push -u origin main
You should now see all the files in the repository on GitHub.
GitHub Continuous Integration
GitHub Actions takes care of the CI (testing code and deploying docs).
Setup development branch
Create a development branch where changes will by pushed for testing/development, before it is merged to the main
branch once it's safe for production.
- Click on the "main" dropdown button your repo's homepage
- Type in "development" in the search bar
- Select "Create branch: development from main".
Note if 'development' is not used. You must change the branch reference in certain files within the '.github/workflows' directory for CI checks to work.
As seen with main, Actions will run for development
. Additionally, whenever you open a pull request (PR) from development
to main
, the checks will automatically run to make sure the code is safe for merging. This is the basic requirement for CI to work.
CI checks exist on the main
and development
branches so these are typically "protected" from having bad code. Having the test pypi before pypi allows for user-testing of a new release without pushing out code that isn't ready for production. Documentation is auto-published when main
is updated.
Create documentation
Github Actions creates a gh-pages
branch with files that are automatically generated from the repository's docs
folder. For more information on how to add pages to this documentation visit MkDocs-Material docs.
To publish these docs to your own GitHub site do the following:
- Go to "Settings" section.
- Scroll down to "GitHub Pages" section.
- Within the "Source" section select
gh-pages
branch and/(root)
. - Click "Save" button.
Scroll back down to "GitHub Pages" and a link should be given for where your docs will be published (wait a few minutes for publication). In addition, this link can be added in the About
section of your repository under "website" to display the link in a convenient location.
Publish to Test PyPI
Release process
The cookiecutter creates a project which has a release action for release candidates and a seperate one for production releases. This is because, before merging into main (and releasing to production) the developer should develop the code on the development
branch. With the development
code ready for production, the developer would create a release candidate (otherwise known as pre-release) which ships the package to test pypi. This is done so the package can be downloaded and user-tested without messing up the release history of your pypi package. In addition, it's typically recommended to only have production-ready code on your main branch.
For this process to work, we require both pypi and test pypi accounts:
Create test PyPI account
Visit test pypi and sign-up for an account. Remember your username and password as it will be needed later on.
Setup repository secrets for test PyPI
Github Secrets allows you to inject secret variables into your Github Actions without them being visible to the public, which is especially important for open-source projects. This cookiecutter's out-of-the-box continous deployment process looks for a few secret variables so we'll set those here.
Navigate to the Settings -> Secrets
section of your repository and add the secrets TEST_PYPI_USERNAME
and TEST_PYPI_PASSWORD
. If you use other variable names, you'll have to change the secret references in .github/workflows/test_pypi_publish.yml
.
Create release candidate
These are the steps needed to publish to test pypi:
- Navigate to the
Releases
section of your repository. - Click "Create a new release".
- Set
Tag version
to0.1.0-rc0
. - Select
development
branch. - Set
Release title
toRelease Candidate: v0.1.0
(or another name). - Select "This is a pre-release"
- Click "Publish release"
Wait a few minutes (or watch the Github Action) for it to be published then visit your test pypi projects page to see the release.
Install package
Now that you code is on test pypi, it can be installed with pip install
using the extra argument --extra-index-url
, allowing pip to also check another registry. The full command is:
pip install your_package_name==0.1.0rc0 --extra-index-url=https://test.pypi.org/simple/`
As there is no release candidates (and therefore no 0.1.0rc0
) on pypi. This command would not be able to find the given release without the extra-index-url
.
Publish to PyPI
Differences in the process
Publishing to PyPi is similar to the above process publishing to test pypi. Here, the main differences are outlined:
- Visit PyPI (not test pypi) and create an account
- Set the given username and password as
PYPI_USERNAME
andPYPI_PASSWORD
. - For release:
- Select
main branch
, - Set tag version to
0.1.0
, - Set release title to
v0.1.0
, - DO NOT select "This is pre-release".
- Select
The pip
command should be:
pip install package-name
or
pip install package-name==0.1.0
if you wish to pin the version number.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.