Skip to content

Commit b737f95

Browse files
lwasserlwasser
committed
bringing package info over to this section
1 parent ac5c988 commit b737f95

File tree

7 files changed

+404
-2
lines changed

7 files changed

+404
-2
lines changed

‎code-style-structure/intro.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
# Code style and structure
22

33

4-
Under development
4+
Under development - possibly remove this as it's in the package structure
5+
and might
6+
make sense there.

‎index.md

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,11 +102,23 @@ documentation/readme-files
102102
documentation/package-documentation-tutorials
103103
```
104104

105+
106+
```{toctree}
107+
:hidden:
108+
:caption: Package structure & code style
109+
110+
intro <package-structure-code/intro>
111+
package-structure-code/code-structure-style
112+
package-structure-code/release
113+
package-structure-code/overview
114+
package-structure-code/collaboration
115+
```
116+
105117
```{toctree}
106118
:hidden:
107119
:caption: Code Style & Structure
108120
109-
code-style-structure/intro
121+
code-style-structure/index
110122
```
111123

112124
```{toctree}

‎package-structure-code/code-structure-style.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Code Style and Structure
2+
3+
pyOpenSci suggests that you follow the [python PEP8 style guide](https://peps.python.org/pep-0008/) for decisions
4+
related to styling your open source Python packages code.
5+
6+
We also suggest that you consider:
7+
1. adhering to a commonly used docstring format. If you use xx or xx then it will further support easy API documentation using tools such as Sphinx autodoc.
8+
2. Adding a linter to your development build that will catch style issues and tell you how to reformat your code as needed. (see below for more )
9+
3. Add a code styler such as black or blue to keep the entire package consistent.
10+
11+
## Docstring styles
12+
13+
```{note}
14+
what is a docstring...
15+
https://peps.python.org/pep-0257/#what-is-a-docstring
16+
```
17+
18+
* https://numpydoc.readthedocs.io/en/latest/
19+
* Ask on slack this week what resources people like for this
20+
21+
## Code linters
22+
23+
Code linters are tools that look at your code and identify problems such as:
24+
25+
* unused variables
26+
* invalide styles
27+
* missing docstrings
28+
* incorrect spacing
29+
30+
and more
31+
32+
Linters can be run as a command-line tool and/or can also be setup as a part of
33+
your favorite programming tool (e.g. VScode, pycharm, etc).
34+
35+
Some maintainers stup a pre-commit hook in their reporisoty. A hook will check
36+
your code prior to your committing it. IT will itendify issues and if the
37+
hook includes a styler, will fix any issues with code style before you commit.
38+
39+
This type of setup can be helpful to ensure code consistency associated with new
40+
contributions...
41+
42+
43+
Regardless of how you set this up, We suggest setting up a linter and a code styler
44+
as they will give you automatic feedback about your code's structure as you (or a contributor) write it.
45+
46+
## Some popular linters
47+
48+
* A very popular code linter for Python is [flake8](https://flake8.pycqa.org/en/latest/).
49+
`Flake8` checks if the code is according to [PEP 8](https://www.python.org/dev/peps/pep-0008/),
50+
the Python Enhancement Proposal about `Style Guide for Python Code`.
51+
52+
53+
See also:
54+
55+
- [mypy](http://mypy-lang.org/)
56+
- [numpydoc](https://numpydoc.readthedocs.io/en/latest/)
57+
- [pydocstyle](https://github.com/PyCQA/pydocstyle)
58+
59+
60+
## Code stylers
61+
62+
Code stylers are tools that fix styling issues in a file, formatting it automatically.
63+
Code *styling* is different from code *linting* because it doesn't change the functionality
64+
of your code at all, it *only* changes how it looks.
65+
Using an automatic formatting tool helps to keep the source code within specification
66+
and also helps review workflow. While stylers might cause your code to look differently
67+
than you would have chosen, many projects have adopted them in order to have a single
68+
code style that is consistent across projects.
69+
70+
Currently, [black](https://github.com/psf/black) is the most popular code styler for Python.
71+
It will format the code according the `PEP 8` and should work fine with `flake8` (maybe it needs
72+
some extra configuration as, for example, `line-length`).
73+
74+
See also:
75+
76+
- [isort](https://github.com/timothycrosley/isort)
77+
78+
79+
## Git pre-commit hook
80+
81+
Git pre-commit hook is a useful tool that checks your code automatically when you run a `git commit` and,
82+
if it fails, the `git commit` is canceled. This is often used to make sure
83+
that the changes to your code match a particular style, or that there are no
84+
code linting errors.
85+
86+
For example, if you want that `git commit` checks if your code matches the PEP8 specification,
87+
you can configure a git flake8 pre-commit hook:
88+
89+
90+
```yaml
91+
# file: .pre-commit-config.yaml
92+
repos:
93+
- repo: https://gitlab.com/pycqa/flake8
94+
rev: '3.7.9'
95+
hooks:
96+
- id: flake8
97+
98+
```
99+
100+
```{note}
101+
See [the flake8 hooks explanation](https://flake8.pycqa.org/en/latest/user/using-hooks.html) for more details.
102+
```
103+
104+
This file specifies a hook that will be triggered automatically before each `git commit`,
105+
in this case, it specifies a flake8 using version `3.7.9`.
106+
107+
Before you can see any change, first you should install `pre-commit` library.
108+
One way to do it is using `pip` or `conda`:
109+
110+
```sh
111+
pip install pre-commit
112+
113+
# or
114+
115+
conda install -c conda-forge pre-commit
116+
```
117+
118+
Now, you can install your pre-commit hook using `pre-commit install`, and it will create the hook based on
119+
the file `.pre-commit-config.yaml`.
120+
121+
Before each `git commit` command, in this case, git will run `flake8` and, if it fails, the `commit` will be canceled.
122+
123+
124+
## What git pre-commit hook should I use?
125+
126+
The git pre-commit hook you should use, depends on the project needs or the team needs.
127+
Some pre-commit hooks you can find useful would be:
128+
129+
- [flake8](https://flake8.pycqa.org/en/latest/user/using-hooks.html)
130+
- [mypy](https://github.com/pre-commit/mirrors-mypy)
131+
- [black](https://black.readthedocs.io/en/stable/integrations/source_version_control.html)
132+
- [isort](https://github.com/pre-commit/mirrors-isort)
133+
134+
If you want more information about `pre-commit`, check out its [documentation](https://pre-commit.com/).

‎package-structure-code/collaboration.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Collaboration Guide
2+
3+
🚧 UNDER CONSTRUCTION - THIS CONTENT SHOULD BE FURTHER DEVELOPED BY THE END OF 2022! KEEP CHECKING BACK TO UPDATES AS THEY ARE IN PROGRESS🚧
4+
5+
6+
Note: pyOpenSci is still building out this section of our guidebook. Many of the examples come from rOpenSci. If you have suggestions for changes, check out the [GitHub repo](https://github.com/pyOpenSci/contributing-guide).
7+
8+
## Make your repo contribution and collaboration friendly
9+
10+
### Code of conduct
11+
12+
We require that you use a code of conduct such as the [Contributor Covenant](https://contributor-covenant.org/) in developing your package. You should document your code of conduct in a `CODE_OF_CONDUCT` file in the package root directory, and link to this file from the `README` file.
13+
14+
### Contributing guide
15+
16+
October 2022 NOTE: we are in the process of updating all of this and will likely deprecate
17+
this cookie cutter. Proceed at your own risk :)
18+
19+
We have a [template for contributing guidelines](https://github.com/pyOpenSci/cookiecutter-pyopensci/blob/master/%7B%7Bcookiecutter.project_slug%7D%7D/CONTRIBUTING.rst) in our cookiecutter repository. Even if you're not using cookiecutter to build your project (see our [packaging guide](../authoring/overview#project-template) for info), you can download our CONTRIBUTING.rst as a starting point.
20+
21+
You can tweak it a bit depending on your workflow and package. For example, make sure contributors have instructions in your CONTRIBUTING file for running local tests if not trivial. CONTRIBUTING can also contain some details about how you acknowledge contributions (see [this section](#attributions)) and the roadmap of your package (cf [this example for R](https://github.com/ecohealthalliance/fasterize/blob/master/CONTRIBUTING.md)).
22+
23+
### Issue labelling
24+
25+
You can use labels such as "help wanted", "good first issue", or "beginner" to help potential collaborators, including newbies, find your repo. For more info, see this [GitHub article](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/encouraging-helpful-contributions-to-your-project-with-labels).
26+
27+
## Working with collaborators
28+
29+
### Onboarding collaborators
30+
31+
There's no general pyOpenSci rule as to how you should onboard collaborators. You should increase their rights to the repo as you gain trust, and you should definitely acknowledge contributions (see [this section](#attributions)).
32+
33+
You can ask a new collaborator to make PRs (see following section for assessing a PR locally, i.e. beyond CI checks) to dev/main and assess them before merging, and after a while let them push to main, although you might want to keep a system of PR reviews... even for yourself once you have team mates!
34+
35+
A possible model for onboarding collaborators is provided by Jim Hester in [his `lintr` repo](https://github.com/jimhester/lintr/issues/318).
36+
37+
If your problem is _recruiting_ collaborators, you can post an open call like Jim Hester's [on Twitter](https://twitter.com/jimhester_/status/997109466674819074), ([GitHub](https://github.com/jimhester/lintr/issues/318)). As an pyOpenSci package author, you can also ask for help from pyOpenSci.
38+
39+
### Working with collaborators (including yourself)
40+
41+
You could implement the "[gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)" philosophy as explained by Amanda Dobbyn in [this rOpenSci blog post](https://ropensci.org/blog/2018/04/20/monkeydo/).
42+
43+
One particular aspect of working with collaborators is reviewing pull requests. Even if not adopting gitflow it might make sense for repo collaborators to make PRs and have them reviewed, and in general PRs by external developers will need to be assessed. Sometimes you'll be fine just reading the changes and trusting [Continuous integration](../authoring/overview#continuous-integration). Sometimes you'll need to dive deeper, e.g. by downloading a copy of the branch that the PR was created from.
44+
45+
(attributions)=
46+
### Be generous with attributions
47+
48+
If someone contributes to your repository consider adding them in CONTRIBUTORS, as contributor for small contributions, author for bigger contributions. Also consider adding their name near the feature/bug fix line in HISTORY We recommend your being generous with such acknowledgements.
49+
50+
If your package was reviewed by pyOpenSci and you feel that your reviewers have made a substantial contribution to the development of your package, you may list them in CONTRIBUTORS as a reviewer. Only include reviewers after asking for their consent.
51+
52+
```{note}
53+
Please do not list pyOpenSci editors and reviewers as contributors to your project.
54+
Your participation in and contribution to pyOpenSci is thanks enough!
55+
```

‎package-structure-code/intro.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Python package structure information
2+
3+
4+
Resources
5+
6+
https://merely-useful.tech/py-rse/
7+
8+
If you plan to submit a package for review to pyOpenSci and are looking for
9+
some guidance on package structure, code formats and style, then this section is for you.
10+
11+
12+
13+
14+
If you are looking for a more comprehensive guide to Python packaging we suggest
15+
you review the following excellent resources:
16+
17+
## TODO: ***** add resource list here *****
18+
19+
```{note}
20+
If you are considering submitting a package to pyOpenSci, or if you are just
21+
getting started with building a package, you may want to have a look at the
22+
bare-minimum [editor checks.](open-source-software-submissions/editor-in-chief-guide.html#editor-checklist-copy-template-below-to-use-in-the-issue) that pyOpenSci
23+
performs before a review even begins.
24+
25+
In general these are basic items that should be in any open software repository.
26+
```
27+
28+
## Packaging Guide
29+
30+
31+
PyPI also has a [short tutorial](https://packaging.python.org/tutorials/packaging-projects/)
32+
on how to package a Python project for easy installation.
33+
34+
35+
<!--
36+
37+
These checks include several items
38+
39+
- **Sufficient Documentation** The package has sufficient documentation available online (README, sphinx docs) to allow us to evaluate package function and scope *without installing the package*. This includes:
40+
Get started tutorials or vignettes that help a user understand how to use the package and what it can do for them (often these have a name like "Getting started")
41+
- **API documentation** - this includes clearly written doc strings with variables defined using a standard docstring format -->
42+
43+

‎package-structure-code/release.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Releasing a package
2+
3+
🚧 UNDER CONSTRUCTION - THIS CONTENT SHOULD BE FURTHER DEVELOPED BY THE END OF 2022! KEEP CHECKING BACK TO UPDATES AS THEY ARE IN PROGRESS🚧
4+
5+
6+
This section covers releasing your package to PyPI as well as releasing future versions. Your package should have different versions over time: snapshots of a state of the package that you can release to PyPI for instance. These versions should be properly _numbered_, _released_ and _described in a NEWS file_. More details below.
7+
8+
9+
## Original Release
10+
11+
After the review process has finished, you're ready to release your package to PyPI so others can find and use your awesome package! Releasing to PyPI is easy. Once your package is ready, register it on PyPI by running:
12+
13+
```
14+
python setup.py register
15+
```
16+
17+
## Releasing Updated Versions
18+
19+
When you update your package, you release a new version to PyPI. Fortunately, this is easy! First, we'll talk about the metadata you'll need to update for each version. Then we'll cover how to release your updated version to PyPI [manually via the command line](manual-release) or [automatically via Travis CI](travis-release).
20+
21+
### Version Naming
22+
23+
* We recommend that pyOpenSci packages use [semantic versioning](https://www.python.org/dev/peps/pep-0440/#semantic-versioning). In addition to the [PEP section on it](https://www.python.org/dev/peps/pep-0440/#semantic-versioning), [the semver website has more detail](https://semver.org/).
24+
25+
* Versioning can be done using [bumpversion](https://github.com/peritus/bumpversion), e.g. for a minor update:
26+
27+
```
28+
bumpversion minor
29+
```
30+
31+
"minor" can be replaced with "major" or "patch" depending on the level of update.
32+
33+
(history)=
34+
### History/News/Changelog file
35+
36+
A HISTORY (or NEWS or CHANGELOG) file describing changes associated with each version makes it easier for users to see what's changing in the package and how it might impact their workflow. You must add one for your package, and make it easy to read.
37+
38+
* It is mandatory to use a `HISTORY` file in the root of your package. It can also be called NEWS or CHANGELOG We recommend using `[NAME].md` or `[NAME].rst` to make the file more browsing-friendly on GitHub (GitHub renders certain file types, including Markdown and reStructured text).
39+
40+
* Update the history file before every PyPI release, with a section with the package name, version and date of release.
41+
42+
```
43+
foobar 0.2.0 (2016-04-01)
44+
=========================
45+
```
46+
47+
* Under that header, put in sections as needed, including: `NEW FEATURES`, `MINOR IMPROVEMENTS`, `BUG FIXES`, `DEPRECATED AND DEFUNCT`, `DOCUMENTATION FIXES` and any special heading grouping a large number of changes. Under each header, list items as needed. For each item give a description of the new feature, improvement, bug fix, or deprecated function/feature. Link to any related GitHub issue like `(#12)`. The `(#12)` will resolve on GitHub in Releases to a link to that issue in the repo.
48+
49+
* After you have added a `git tag` and pushed up to GitHub, add the news items for that tagged version to the Release notes of a release in your GitHub repo with a title like `pkgname v0.1.0`. See [GitHub docs about creating a release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository).
50+
51+
(manual-release)=
52+
### Releasing Versions: Manual
53+
54+
To manually upload a new package version to PyPI, follow these steps:
55+
56+
1. Update your HISTORY file as described [above](#history)
57+
2. Open `setup.py` and change the version, e.g., version='1.0.3'
58+
3. If you added new, non-Python files to the project that need to be distributed as well, e.g., configuration files, add them to `MANIFEST.in`. This does not need to be done for Python code files ending in .py.
59+
4. Open a terminal and go into the parent of the project's root dir
60+
5. `python setup.py sdist`
61+
6. Check the resulting files, especially the egg file: are all the files contained?
62+
7. If everything is ok, upload the new version to PyPI: `python setup.py sdist upload`
63+
64+
That's it!
65+
66+
(travis-release)=
67+
### Releasing via Travis CI
68+
Instead of manually uploading new package versions, Travis can be configured to automatically upload new versions. If you use this, each time you tag a new release and push it to GitHub, Travis will release it to PyPI (assuming it passes testing).
69+
70+
* The pyOpenSci cookiecutter comes with this option mostly set up. For details on how to finish the set up, see [this guide](https://cookiecutter-pyopensci.readthedocs.io/en/latest/travis_pypi_setup.html).
71+
72+
* Also, be sure to check out this [PyPI release checklist](https://cookiecutter-pyopensci.readthedocs.io/en/latest/pypi_release_checklist.html).
73+

0 commit comments

Comments
 (0)