You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+5-4Lines changed: 5 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,13 @@
1
1
# How to contribute
2
2
3
3
## TLDR (Too long; didn't read)
4
-
*open a [GitHub Issue](https://github.com/organizationname/samplepackagename/issues/new/choose) describing what you want to do
5
-
*[fork](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) the main branch and clone it locally
6
-
*[create a branch](https://docs.github.com/en/get-started/using-github/github-flow#create-a-branch) for your edits
4
+
*[fork](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) the [repository](https://github.com/organizationname/samplepackagename) using the `Fork` button on GitHub.
5
+
*clone your forked repository on your computer with `git clone https://github.com/organizationname/samplepackagename`.
6
+
*[create a branch](https://docs.github.com/en/get-started/using-github/github-flow#create-a-branch) for your edits with `git branch new-branch`
7
7
* make your changes and run the style checkers with `nox -s style`
8
8
* once the style checks pass, commit your changes with `git commit -m "a short description of your changes"`
9
-
*[make a Pull Request](http://makeapullrequest.com/) for your branch
9
+
* push your changes with `git push -u origin new-branch`
10
+
*[make a Pull Request](http://makeapullrequest.com/) for your branch from the main GitHub repository [PR page](https://github.com/organizationname/samplepackagename/pulls).
10
11
11
12
🎉 Thanks for considering contributing to this package! 🎉
This template is based on the [Scientific Python Development Guide](https://learn.scientific-python.org/development/). The main differences with the [template they provide](https://github.com/scientific-python/cookie) is that this is an _opinionated_ template, where I made certain decision I feel are optimal. Additional, this is setup for packages which have complex non-Python dependencies which can be installed with `pip`, but require `conda`. This is useful if your package will depends on packages such as `GeoPandas`, `PyGMT`, or `Cartopy`, as these all depend on code written in C or C+ which is easiest to install with conda.
6
4
7
-
[![PyPI version][pypi-version]][pypi-link]
8
-
[![Conda-Forge][conda-badge]][conda-link]
9
-
[![PyPI platforms][pypi-platforms]][pypi-link]
5
+
The below steps will create a complete Python package with testing, a documentation website, and builds uploaded to both PyPI (pip) and Conda-Forge (conda) for each new version release in GitHub. While it is quite tedious to initially setup, once you finished the below steps, almost everything is automated. The documentation website is automatically generated for each new PR, and new package versions are automatically released to PyPI and Conda-Forge each time you manually create a GitHub release.
The below steps will create a complete Python package with testing, a documentation website, and versions upload to both PyPI (pip) and Conda-Forge (conda) for each new version release in GitHub.
11
+
## Template Instructions
16
12
17
13
Steps:
18
14
1) Initiate your repository:
@@ -75,25 +71,76 @@ Steps:
75
71
- Dependency version's should only be constrained to specific versions if you know there is an issue, and they should almost never be pinned to specific versions, as this will cause many issues foranyone who wants to use your packagein their own environments.
76
72
- this template also includes files and commands to create `conda` environments. These are used both in developing, and in GitHub automations. You need to manually ensure the dependencies listed in`environmental.yml` match those in`pyproject.toml`. Include all optional dependencies in the `environmental.yml`. If a dependency is only available via pip, and not conda, add it at the bottom to be installed via pip.
77
73
5) Create environment, style check, test, and commit your changes.
78
-
- follow the instructions in`CONTRIBUTING.md` from section `Setting up nox` to the bottom.
79
-
6) Set up publishing on PyPI
80
-
- First, we test the setup by publishing to Test-PyPI to ensure everything works before publishing to the real PyPI.
81
-
- make an account on [TestPyPI](https://test.pypi.org/).
82
-
- under 'Your Projects', and 'Publishing', 'Add a new pending publisher', fill out your info.
83
-
- the project name and repository name should be what you chose for`samplepackagename`.
84
-
- the owner should be what you used from `organizationname`.
85
-
- Workflow name should be `cd.yml`
86
-
- Environment name should be `pypi`
87
-
- Note that this doesn't reserve your package name until you make your first actual release!
88
-
- On GitHub, make a release.
89
-
3) Set up publishing on Conda-Forge
90
-
- create a conda-forge feedstock
91
-
4) Set up ReadTheDocs for the documentation website
92
-
-
93
-
5) Zenodo release
94
-
- add DOI to `docs/citing.md`
95
-
6) Finalize
96
-
- remove all the above instructions and
74
+
- follow the instructions in`CONTRIBUTING.md` starting at section `Setting up nox` and stopping before `Publish a new release`.
75
+
- these steps should result in a merged PR with your code.
76
+
6) Set up automated Zenodo releases
77
+
- if you haven't already, link your organization (or personal) GitHub account to [Zenodo](https://zenodo.org/) using `Linked accounts` under your Zenodo profile.
78
+
- do to the `GitHub` menu on your Zenodo profile.
79
+
- click the Sync button and then turn on the switch for your repository.
80
+
- any future GitHub releases should now result in a new Zenodo release automatically.
81
+
7) Set up publishing on TestPyPI
82
+
- before publishing to the real PyPI, we will publish to Test-PyPI to ensure everything works .
83
+
- make an account on [TestPyPI](https://test.pypi.org/).
84
+
- under 'Your Projects', and 'Publishing', 'Add a new pending publisher', fill out your info.
85
+
- the project name and repository name should be what you chose for `samplepackagename`.
86
+
- the owner should be what you used from `organizationname`.
87
+
- Workflow name should be `cd.yml`
88
+
- Environment name should be `pypi`
89
+
- note that this doesn't reserve your package name until you make your first actual release!
90
+
8) Make a GitHub release
91
+
- On the main GitHub page, on the right side click `Create a new release`.
92
+
- click `Select tag` and type`v0.0.1`.
93
+
- set a Release title: "Initial release"
94
+
- click `Publish release`
95
+
- this should automatically trigger a few things:
96
+
1) a DOI will be added to your Zenodo, add this DOI to `docs/citing.md`.
97
+
2) the GitHub action `CD` should be triggered, create a release of `v0.0.1` to TestPyPI.
98
+
- to test this worked correctly, run the below commands to create a new conda environment using the TestPiPI release, and run your codes tests.
- If the install and test above worked then we can change from TestPyPI to normal PyPI.
107
+
- in`.github/workflows/cd.yml` comment out or delete the last line: `repository-url: https://test.pypi.org/legacy/`. Now any future reruns of this action will release to PyPI.
108
+
- In this case, since the GitHub release has already been made, we need to manually trigger the `CD` workflow in GitHub.
109
+
- At [this link](https://github.com/organizationname/samplepackagename/actions/workflows/cd.yml), click the `Run workflow` button.
110
+
- This should build the package and release it to PyPI.
111
+
10) Set up publishing on Conda-Forge
112
+
- create a [conda-forge recipe and feedstock](https://conda-forge.org/docs/maintainer/adding_pkgs/#creating-recipes) with the below instructions:
113
+
- Create a new environment using :`mamba create --name grayskull grayskull`
114
+
- Activate this new environment :`conda activate MY_ENV`
115
+
- Generate the recipe :`grayskull pypi --strict-conda-forge https://github.com/organizationname/samplepackagename`
116
+
- this should create a `meta.yaml` file, which is the recipe.
117
+
- fork and clone the [stage-recipes](https://github.com/conda-forge/staged-recipes) repository on conda-forge.
118
+
- checkout a new branch :`git checkout -b samplepackagename`
119
+
- create a new folder :`staged-recipes/recipes/samplepackagename`
120
+
- copy your `meta.yaml` file into this folder, remove the `meta.yaml` from wherever it was generated.
121
+
- commit and push your changes to your fork, and in the main [repository](https://github.com/conda-forge/staged-recipes) open a PR.
122
+
11) Set up ReadTheDocs for the documentation website
123
+
- log into ReadTheDocs using your GitHub account.
124
+
- click `Add project` and ssearch for your repository.
125
+
- Chose your project name, ideally its the same as your package name, but it doesn't have to be. If it's different, update the badge below: `[rtd-link]: https://samplepackagename.readthedocs.io/en/latest/?badge=latest`
126
+
- Go to `settings` to update anything you'd like
127
+
- check `Build pull requests for this project`.
128
+
- for each commit to main, ReadTheDocs should automatically update the documentation website. Also, in PR's there should be a link to view the new docs to check them before merging the PR.
129
+
12) Finalize
130
+
- remove all the above instructions and raise any issues in this template's repository if you have any suggestion or found any errors in this template!
131
+
- if you want, please submit a PR to this repository to add your package to this list at the top of this README to showcase it!
These instructions assume you have `Make` installed. If you don't you can just open up the `Makefile` file and copy and paste the commands into your terminal. This also assumes you have Python installed.
127
-
128
-
Install the required dependencies with either `conda` or `mamba`:
129
-
130
-
cd samplepackagename
131
-
132
-
make create
133
-
134
-
Activate the newly created environment:
135
-
136
-
mamba activate samplepackagename
137
-
138
-
Install the local project
139
-
140
-
make install
141
-
142
-
143
-
## How to use
144
-
145
-
To use this code, you need to first import the package. There are two options:
146
-
147
-
### 1: Import the main package
148
-
149
-
For example:
150
-
```python
151
-
import samplepackagename
152
-
```
153
-
154
-
will allow you to access the function`example_function()` with either `samplepackagename.module1.example_function()` or just `samplepackagename.example_function()`.
155
-
156
-
Functions accessed in this way need to be explicitly added to the file `src/samplepackagename/__init__.py`
157
-
158
-
### 2: Import each module individually
159
-
160
-
For example:
161
-
```python
162
-
from samplepackagename import module1
163
-
```
164
-
Will allow you to access the function`example_function()` with `module1.example_function()`.
165
-
166
-
## Developer instructions
167
-
168
-
See the contributors guide for more details.
169
-
170
-
- Fork the [repository](https://github.com/organizationname/samplepackagename) using the `Fork` button on GitHub.
171
-
- Clone your forked repository on your computer with `git clone https://github.com/organizationname/samplepackagename`.
172
-
- Make a new branch with `git branch new-branch`
173
-
- Make your changes
174
-
- Add tests to make sure you changes are robust
175
-
- Style-check your code:
176
-
177
-
nox -s style
178
-
- Test your code
179
-
180
-
nox -s test
181
-
- If necessary, update dependencies in both `environment.yml` and `pyproject.toml`. Then with your conda environment activated run:
Copy file name to clipboardExpand all lines: docs/citing.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,4 +4,4 @@ This is research software made by scientists. Citations help us justify the effo
4
4
5
5
If you used `samplepackagename` in your research, please consider citing our software.
6
6
7
-
If you would like to cite the specific version you used, which can improve reproducibility and let users know the state of the software at the time of your analysis, please use the version-specific citation and DOI (available from [Zenodo](https://zenodo.org/doi/)).
7
+
If you would like to cite the specific version you used, which can improve reproducibility and let users know the state of the software at the time of your analysis, please use the version-specific citation and DOI (available from [Zenodo](https://doi.org/10.5281/zenodo.15863068)).
0 commit comments