Skip to content

feat(contrib file): update to contributing and links to other resources #440

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Feb 11, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions documentation/repository-files/code-of-conduct-file.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
(coc-file)=

# The CODE_OF_CONDUCT file - Python Packaging

```{admonition} Example CODE_OF_CONDUCT files
Expand Down
69 changes: 54 additions & 15 deletions documentation/repository-files/contributing-file.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,64 @@
# Contributing File in your Python Open Source Package
(contributing-file)=
# Your Python Package CONTRIBUTING File

The **CONTRIBUTING.md** is the landing page guide for your project's contributors. It outlines how contributors can get involved, the contribution types that you welcome, and how contributors should interact or engage with you and your maintainer team. The contributor guide should also link to get-started resources that overview how to set up development environments, what type of workflow you expect on GitHub/GitLab, and anything else that contributors might need to get started.

This file benefits maintainers and contributors. For contributors, it provides a roadmap that helps them get started and makes their first contribution easier. For maintainers, it answers commonly asked questions and reduces the burden of explaining your process to every person who wants to contribute. This document creates a more collaborative and efficient development process for everyone.

## CONTRIBUTING files lower barriers to entry

The contributing file lowers barriers to entry for new and seasoned contributors as it provides a roadmap.

- **For Contributors**: It provides clear instructions on contributing, from reporting issues to submitting pull requests.
- **For Maintainers**: It streamlines contributions by setting expectations and standardizing processes, reducing the time spent clarifying common questions or handling incomplete issues or pull requests.

Including a well-written CONTRIBUTING.md file in your project is one way of making it more welcoming and open to new and seasoned contributors. It also helps create a smoother workflow for everyone involved.

## Make it welcoming

Make the guide welcoming. Use accessible language to encourage participation from contributors of all experience levels. For example:

- Avoid technical jargon or explain terms when necessary (for example, "fork the repository").
- Include a friendly introduction, such as "Thank you for your interest in contributing! We're excited to collaborate with you."
- Highlight that all contributions, no matter how small, are valued.

## What a CONTRIBUTING.md file should contain

```{admonition} Example contributing files
:::{admonition} Example contributing files
:class: tip

* [pyGMT contributing file](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md)
* [fatiando verde's contributing file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md)
```
- [PyGMT contributing file](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md)
- [Verde's contributing file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md)
:::

Your Python open source package should include a file called **CONTRIBUTING.md** located in the
root of your repository (with your **README.md** file).
Your Python package should include a file called **CONTRIBUTING.md** located in the
root of your repository next to [your **README.md** file](readme-file).

The contributing file should include information about the types
of contributions that you welcome, and how you'd like to see
contributions happen.
The CONTRIBUTING.md file should include information about:

- The types of contributions that you welcome

> Example: We welcome contributions of all kinds. If you want to address an existing issue, check out our issues in this repository and comment on the one that you'd like to help with. Otherwise, you can open a new issue...

- How you'd like contributions to happen. Clearly outline your contribution process. For example:
- Should contributors address open issues
- Are new issues welcome?
- Should contributors open a pull request (PR) directly or discuss changes first?

- Include instructions for the fork and pull request workflow and link to resources or guides explaining these steps (if available).
- Guidelines that you have in place for users submitting issues, pull requests, or asking questions.

If you have a [development guide](development-guide), link to it. This guide should provide clear instructions on how to set up your development environment locally. It also should overview CI tools that you have that could simplify the contribution process (for example, pre-[commit.ci bot](https://www.pyopensci.org/python-package-guide/package-structure-code/code-style-linting-format.html#pre-commit-ci), and so on), [linters, code formatters](https://www.pyopensci.org/python-package-guide/package-structure-code/code-style-linting-format.html#code-linting-formatting-and-styling-tools), and so on.

This guide should also include information for someone
interested in asking questions, submitting issues or pull requests. It should have things like:
interested in asking questions. Some projects accept questions as GitHub or GitLab issues. Others use GitHub discussions, Discourse, or even a Discord server.

The contributing file should also include:

- A link to your [code of conduct](coc-file)
- A link to your project's [LICENSE](license-file)
- A link to a [development guide](development-guide) if you have one

## Summary

* Any guidelines that you have in place for users submitting issues, pull requests or asking questions.
* A link to your code of conduct
* A link to licensing information found in your README file.
* A link to a development guide if you have one
A well-crafted CONTRIBUTING.md file is welcome mat for your project! By providing clear instructions, helpful resources, and a welcoming tone, you make it easier for contributors to get involved and build a stronger, more collaborative community around your project.
5 changes: 2 additions & 3 deletions documentation/repository-files/development-guide.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
(pyos-development-guide)=
# What the development guide for your Python package should contain

Ideally, your package should also have a development guide. This file may live in your package documentation and should be linked to from your CONTRIBUTING.md file (discussed above).
Expand All @@ -9,6 +10,7 @@ technically proficient users how to:
* Build documentation locally

The development guide should also have guidelines for:

* code standards including docstring style, code format and any specific code approaches that the package follows.

It's also helpful to specify the types of tests you request if a contributor submits a new feature or a change to an existing feature that will not be covered by your existing test suite.
Expand Down Expand Up @@ -38,14 +40,11 @@ pyOpenSci requires a package to have in order to be eligible for
review. Some maintainers may also opt to include the development information in their contributing guide.
```


```{tip}
[The Mozilla Science Lab website has a nice outline of things to consider when
creating a contributing guide](https://mozillascience.github.io/working-open-workshop/contributing/)
```



<!--
pyOpenSci packages must:

Expand Down
14 changes: 6 additions & 8 deletions documentation/repository-files/license-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,11 @@ bibliography:
- ../../bibliography.bib
---

(license-file)=

# License files for scientific Python open source software

:::{button-link} https://www.pyopensci.org/about-peer-review/
:::{button-link} <https://www.pyopensci.org/about-peer-review/>
:color: primary
:class: sd-rounded-pill float-left

Expand All @@ -30,7 +32,6 @@ and more.

[Read more about why license files are critical in protecting both you as a maintainer and your users of your scientific Python open source package.](https://opensource.guide/legal/#just-give-me-the-tldr-on-what-i-need-to-protect-my-project)


## Where to store your license

Your `LICENSE` file should be stored at root of your GitHub / GitLab repository.
Expand Down Expand Up @@ -60,7 +61,7 @@ Free and open source software is intrinsically political, and it is important to
### How to choose a license

To select your license, we suggest that you use GitHub's
[Choose a License tool ](https://choosealicense.com/).
[Choose a License tool](https://choosealicense.com/).

If you choose your license when creating a new GitHub repository, you can also
automatically get a text copy of the license file to add to your repository. However
Expand Down Expand Up @@ -114,7 +115,6 @@ They have fewer **inbound** restrictions - a GPL-3 licensed package can include
| <i class="fa-solid fa-x" style="color: Crimson"></i> | | Copyleft | Permissive |
| <i class="fa-solid fa-check" style="color: MediumSeaGreen"></i> | | Copyleft | Copyleft |


:::{admonition} An example of how a license determine how code can be reused
:class: note

Expand All @@ -128,16 +128,14 @@ This would not be true with a GPL licensed package. `GPL-3` packages can include
🚨 Proceed with caution! 🚨
:::

## What about software citation?

## What about software citation?

While many permissive licenses do not require citation we STRONG encourage that you cite all software that you use in papers, blogs and other publications. You tell your users how to cite your package by using a [citation.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files). We will cover this topic when we talk about creating DOI's for your package using zenodo.
While many permissive licenses do not require citation we STRONG encourage that you cite all software that you use in papers, blogs and other publications. You tell your users how to cite your package by using a [citation.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files). We will cover this topic when we talk about creating DOI's for your package using Zenodo.

<!-- TODO: add link when lesson is created - but also we don't yet know how citation.cff files work with Zenodo (do they work??) will the citation info update with a new Zenodo link

These files - we need to understand if that date releases auto populates or forces zenodo to modify it's citation. If it's not dynamic it could be problematic


-->

# References
Expand Down
8 changes: 5 additions & 3 deletions documentation/repository-files/readme-file-best-practices.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
(readme-file)=

# README File Guidelines and Resources

Your **README.md** file should be located in the root of your GitHub repository.
Expand All @@ -11,8 +13,8 @@ The README.md file is the landing page of:

Your README.md file is also used as a measure of package and community
health on sites such as:
* [GitHub community health for MovingPandas (available for all repositories)](https://github.com/anitagraser/movingpandas/community) and [Snyk - moving pandas example](https://snyk.io/advisor/python/movingpandas)

* [GitHub community health for MovingPandas (available for all repositories)](https://github.com/movingpandas/movingpandas/community) and [Snyk - MovingPandas example](https://snyk.io/advisor/python/movingpandas)

```{figure} /images/pandera-python-package-readme-github.png
---
Expand Down Expand Up @@ -52,10 +54,11 @@ Your README file should have the following information:
Your **README.md** file should contain the following things (listed from top to bottom):

### ✔️ Your package's name

Ideally your GitHub repository's name is also the name of your package. The more
self explanatory that name is, the better.

### ✔️ Badges for current package version, continuous integration and test coverage
### ✔️ Badges for current package version, continuous integration and test coverage

Badges are a useful way to draw attention to the quality of your project. Badges
assure users that your package is well-designed, tested, and maintained. They
Expand Down Expand Up @@ -85,7 +88,6 @@ a badge to add to your repository that shows that it has been reviewed.

```


```{caution}
Beware of the overuse of badges! There is such a thing as too much of a good thing (which can overload a potential user!).
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,6 @@

what's missing

- missing explanation of `requires-python =` in this page -- discussed in slack with pradyun --

::: -->

:::{admonition} Important pyproject.toml take aways
Expand All @@ -21,7 +19,6 @@ what's missing

:::


:::::{todo}

when these are published, remove this todo
Expand Down Expand Up @@ -184,10 +181,9 @@ The examples at the bottom of this page contain ...

- **`[project.scripts]` (Entry points):** Entry points are optional. If you have a command line tool that runs a specific script hosted in your package, you may include an entry point to call that script directly at the command line (rather than at the Python shell).

- Here is an example of[ a package that has entry point script](https://github.com/pyOpenSci/update-web-metadata/blob/main/pyproject.toml#L60)s. Notice that there are several core scripts defined in that package that perform sets of tasks. The pyOpenSci is using those scripts to process their metadata.
- Here is an example of[a package that has entry point script](https://github.com/pyOpenSci/pyosMeta/blob/main/pyproject.toml#L60)s. Notice that there are several core scripts defined in that package that perform sets of tasks. The pyOpenSci is using those scripts to process their metadata.
- **Dynamic Fields:** if you have fields that are dynamically populated. One example of this is if you are using scm / version control based version with tools like `setuptooms_scm`, then you might use the dynamic field, such as version (using scm) **dynamic = ["version"]**


## Add dependencies to your pyproject.toml file

The pyproject.toml file can also be used as a replacement for the requirements.txt file which has been traditionally used to store development dependencies such as pytest, code formatters such as Black and documentation tools such as sphinx.
Expand Down
Loading