From abcfffbc9bb0e264fb8ea731fb331e5b5d69c23a Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 21 Jan 2025 12:55:55 -0700 Subject: [PATCH 1/7] fix: update to contributing and links --- .../repository-files/code-of-conduct-file.md | 2 + .../repository-files/contributing-file.md | 70 +++++++++++++++---- .../repository-files/development-guide.md | 6 +- .../repository-files/license-files.md | 12 ++-- .../readme-file-best-practices.md | 8 ++- 5 files changed, 70 insertions(+), 28 deletions(-) diff --git a/documentation/repository-files/code-of-conduct-file.md b/documentation/repository-files/code-of-conduct-file.md index c5cbc502b..95264cd79 100644 --- a/documentation/repository-files/code-of-conduct-file.md +++ b/documentation/repository-files/code-of-conduct-file.md @@ -1,3 +1,5 @@ +(coc-file)= + # The CODE_OF_CONDUCT file - Python Packaging ```{admonition} Example CODE_OF_CONDUCT files diff --git a/documentation/repository-files/contributing-file.md b/documentation/repository-files/contributing-file.md index 6b7145246..3e470945c 100644 --- a/documentation/repository-files/contributing-file.md +++ b/documentation/repository-files/contributing-file.md @@ -1,25 +1,65 @@ -# 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 to getting started making 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 (e.g., "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) +- [fatiando verde's contributing file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md) +::: + +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.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 open to. Otherwise, you can open a new issue... -Your Python open source package should include a file called **CONTRIBUTING.md** located in the -root of your repository (with your **README.md** file). +- 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? -The contributing file should include information about the types -of contributions that you welcome, and how you'd like to see -contributions happen. +- 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 and CI tools that you have that could simplify the contribution process (e.g. pre-commit.ci bot, etc), linters, code formatters, etc. 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. diff --git a/documentation/repository-files/development-guide.md b/documentation/repository-files/development-guide.md index 7bba5b56d..840137d21 100644 --- a/documentation/repository-files/development-guide.md +++ b/documentation/repository-files/development-guide.md @@ -1,3 +1,5 @@ +(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). @@ -9,6 +11,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. @@ -38,14 +41,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/) ``` - - # References diff --git a/documentation/repository-files/readme-file-best-practices.md b/documentation/repository-files/readme-file-best-practices.md index 1275791a8..8d9a6129a 100644 --- a/documentation/repository-files/readme-file-best-practices.md +++ b/documentation/repository-files/readme-file-best-practices.md @@ -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. @@ -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/anitagraser/movingpandas/community) and [Snyk - moving pandas example](https://snyk.io/advisor/python/movingpandas) ```{figure} /images/pandera-python-package-readme-github.png --- @@ -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 @@ -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!). ``` From 413a433587fb07b113577ebc7a7b74bae2422df6 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 11 Feb 2025 15:27:17 -0700 Subject: [PATCH 2/7] fix: edits from @hugovk Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- documentation/repository-files/contributing-file.md | 10 +++++----- documentation/repository-files/license-files.md | 2 +- .../repository-files/readme-file-best-practices.md | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/documentation/repository-files/contributing-file.md b/documentation/repository-files/contributing-file.md index 3e470945c..94576e1fd 100644 --- a/documentation/repository-files/contributing-file.md +++ b/documentation/repository-files/contributing-file.md @@ -19,7 +19,7 @@ Including a well-written CONTRIBUTING.md file in your project is one way of maki 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 (e.g., "fork the repository"). +- 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. @@ -28,8 +28,8 @@ Make the guide welcoming. Use accessible language to encourage participation fro :::{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 package should include a file called **CONTRIBUTING.md** located in the @@ -49,10 +49,10 @@ The CONTRIBUTING.md file should include information about: - 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 and CI tools that you have that could simplify the contribution process (e.g. pre-commit.ci bot, etc), linters, code formatters, etc. +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 and CI tools that you have that could simplify the contribution process (for example, pre-commit.ci bot), linters, code formatters, and so on. This guide should also include information for someone -interested in asking questions. Some projects accept questions as GitHub or GitLab issues. Others use GitHub discussions, Discourse or even a discord server. +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: diff --git a/documentation/repository-files/license-files.md b/documentation/repository-files/license-files.md index 4e4c8d716..1144e2ed8 100644 --- a/documentation/repository-files/license-files.md +++ b/documentation/repository-files/license-files.md @@ -130,7 +130,7 @@ This would not be true with a GPL licensed package. `GPL-3` packages can include ## 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. :::{admonition} Important pyproject.toml take aways @@ -21,7 +19,6 @@ what's missing ::: - :::::{todo} when these are published, remove this todo @@ -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.