From 20eb89e5a198a979213d08f1afda276b408be70c Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 14:35:10 -0600 Subject: [PATCH 01/52] Add: ci and pr's content --- community/github/continuous-integration.md | 106 +++++++++++ community/github/intro.md | 7 + community/github/our-repositories.md | 2 +- community/github/pull-requests.md | 199 +++++++++++++++++++++ community/index.md | 1 - 5 files changed, 313 insertions(+), 2 deletions(-) create mode 100644 community/github/continuous-integration.md create mode 100644 community/github/pull-requests.md diff --git a/community/github/continuous-integration.md b/community/github/continuous-integration.md new file mode 100644 index 0000000..a6f2679 --- /dev/null +++ b/community/github/continuous-integration.md @@ -0,0 +1,106 @@ +# 3. Continuous integration + +## What is CI? + +Continuous Integration (CI) refers to checks and tests that run on every change (or commit) to a GitHub repository. In the pyOpenSci organization, each commit +triggers at least one or more automated CI workflows. For the website and sphinx books this build will: + +* build the live rendered version of the online content with any changes added in the current commit(s) or pull requests. +* check the text for spelling issues, check images for missing alt tags and more + +If the repository has code, it will check for code style. + +Having a CI setup on each pyOpenSci github repository ensures that we detect issues such as bad links, or broken code, before it's merged into the main repository. + +### What do the green and red checks mean? + +The green and red checks in the CI block indicate the status of these automated +checks: + +* **Green Checks**: These indicate that the code has passed the CI checks. This means the code meets the project's standards and is likely +free from errors or issues related to the specific checks that have passed. + +* **Red X's**: These indicate that the code has failed the associated CI checks. This means there are issues that need to be addressed before the code can be merged. The issues could be related to code style, formatting, tests, or other criteria specified by the CI configuration. + +#### If a CI check is red: + +1. **Click on "Details"** next to the failed check to get more information about the failure. +2. **Review the logs or output** provided to understand what went wrong. +3. **Make the necessary changes** to fix the issue. +4. **Push the updated code** to the pull request to trigger the CI checks again. + +If something isn't working as expected or you are having a hard time understanding why CI is failing (we've all been there!) please ping someone else in the organization for help. As a pyOpenSci community, we are always here to help each other. + +If all CI checks are green, you are good to go. Ping someone to review your pull request. The pull request can be merged once you have a approval from another repository owner. + +:::{note} +Generally we require a single passing approval in order to merge a pull request. however, in some cases, if you are a pyOpenSci staff member or community member with admin / write access, it could be the case that you need to merge something immediately (ie fixing a small piece of breaking code, a spelling error, or adding a new piece of content that has already been agreed upon). +::: + + +## CI and outside contributors + +If someone from outside of the pyOpenSci organization submits a pull request, then someone within the organization needs to approve and run CI. If you +have those super powers, please go ahead and allow CI to run for new contributors. You can’t break anything by running CI so always feel confident in our repos clicking that button if the PR is legitimate and submitted from a valid user! + +Next to each CI step that was run, there is a details button. If you click on that link, it will give you more information about what has run / not run as expected in the build. + +## Website CI checks +All of our website repositories have several CI builds including: + +1. A link checker +2. htmlproofer that checks both links and alt tags, images +3. a CI build that shows you what the rendered site looks like when built online. Currently we are using CircleCI for that live rendered build as CircleCi allows for in browser website build checks. GitHub requires you to download, unzip and view and archive with the build site locally. + + +(pre-commit-ci)= +## About the Pre-Commit CI Bot + +The [Pre-commit CI bot](https://pre-commit.ci/) is a continuous integration service that automatically +runs pre-commit hooks on each pull request. This helps maintain code quality +and consistency without requiring developers to run pre-commit locally. + +TO run the bot on a pr, add the command below to a comment: + +`pre-commit autofix` + +When you do this, the bot will run all of the hooks that it can in place adding +a new commit to the pull request for you. + +#### What the Bot Can Fix + +The bot can fix many linting and style issues in our content in place including: + +* Automatically fix formatting issues such as trailing whitespace and missing + newlines. +* Apply code style adjustments as specified by hooks like `black` and `isort`. + +#### What the Bot Can’t Fix + +The bot can't fix some things such as: + +* Logical errors or bugs in the code. +* Issues that require human judgment, such as resolving complex merge + conflicts or making design decisions. +* Spelling errors + +In the case that the bot finds errors that it can't fix, you will need to +make those changes locally. + +### Using the Bot Instead + +pyOpenSci contributors may prefer not to set up pre-commit locally. In that case, +we can rely on the pre-commit.ci bot to fix things as needed. + +#### Bot setup + +To setup the bot in a new repository: + +1. **Enable pre-commit.ci** on your repository through the + [pre-commit.ci website](https://pre-commit.ci/). +2. The bot will automatically run checks and apply fixes on pull requests. +3. Review the bot's output and ensure all checks pass before merging your code. + +This approach ensures that all contributions meet our pyOpenSci code and +text quality standards without requiring each contributor to install and run +pre-commit locally. diff --git a/community/github/intro.md b/community/github/intro.md index cc9a4d1..530c963 100644 --- a/community/github/intro.md +++ b/community/github/intro.md @@ -1,5 +1,12 @@ # GitHub +:::{toctree} +:glob: +:maxdepth: 2 + +* +::: + :::{todo} 1. for extra contributors - A pyOpenSci community member will review your post / contribution. you don't need to request a review. 1. diff --git a/community/github/our-repositories.md b/community/github/our-repositories.md index 0aa379a..e8cf804 100644 --- a/community/github/our-repositories.md +++ b/community/github/our-repositories.md @@ -1,4 +1,4 @@ -# Our Repositories +# 1. Our Repositories :::{todo} Add repositories from the pyOpenSci organization. diff --git a/community/github/pull-requests.md b/community/github/pull-requests.md new file mode 100644 index 0000000..5f5d727 --- /dev/null +++ b/community/github/pull-requests.md @@ -0,0 +1,199 @@ +# 2. pyOpenSci pull request process + +When possible, pull request and issue submissions and reviews should follow standard open source workflows. Below are guidelines for pull requests. + +## Pull Requests + +Authors of new pull requests should whenever possible, do their best to create clean pull requests. A clean pull request: + +* is focused, and easy to review, +* can be more quickly reviewed (and in turn merged) so it saves everyone time. +* closes an existing issue (with the exception of new content such as blog posts that we manage internally using Asana) + +:::{tip} +Review your own pull request before asking someone else to review it for you. You might be surprised that you notice things in the pull request that you didn't notice when working on the content locally. +::: + +1. **Keep It Small**: Aim for one logical change per pull request to simplify review. +1. **Create descriptive PR Title and Summary**: Clearly state what the PR achieves and why, including any related issue numbers or discussions. +1. **Double check that the files committed to the pull request clearly align with the suggested changes being made in the pull request**. For example if a new guidebook page contains images, all images that are new to the guidebook should be included in the list of files in the pr. If the new page reuses images, then link to the existing images in the repository rather than re-adding them. +1. **Follow Coding / style guide and other organization Standards (if applicable)**: Stick to the project's coding guidelines for style and organization if they exist. This is more often relevant to code pull requests than text. +1. **Review Your Own Pull request first**: Look over your PR critically before requesting reviews to catch any mistakes early. +1. **Respond Respectfully**: Be open to feedback and discuss suggestions to improve the project. +1. **Check CI for any red x's (more on CI below)**: If your pull request returns a red X in the "checks/CI" section, then it's worth seeing if you can figure out what is broken in the build. If you aren't sure - no problem. Leave a note for the reviewer to allow them to help you understand what needs to be fixed (if anything). + +### Highly Recommended + +1. **Create clear Commit Messages**: Explain why changes are made, not just what was changed. +1. **Keep Your Branch Updated**: Regularly rebase your fork from the main branch (is possible) to avoid / clean up any merge conflicts and to keep your PR up to date. + +:::{info} +* [tips for better pull requests](https://opensource.com/article/18/6/anatomy-perfect-pull-request) +::: + +### Regular vs New Contributors + +There is no right or wrong when it comes to building a website repository locally. pyOpenSci staff and other community members who contribute to pyOpenSci regularly will often opt to build online +resources locally for live interactive development and edits. Building locally +is an ideal way for internal contributors to double check website updates before pushing to github and looking at GitHub action updates. + +Contributors making less-regular contributions, or those submitting quick fixes to pages on our website, might opt to use our continuous integration (CI) checks as a way to double check the website build and also to check for broken and bad links, missing alt tags and more within a pull request. + +A large volume of the content in our GitHub repositories is text based +documentation and tutorials. For text based repositories such as our +website, packaging guide and peer review guide, we have CI platforms setup that allow a contributor to submit a pull request with a change, without needing to build the site locally. + +### Supporting new contributors + +pyOpenSci strives to support new and existing contributors in enhancing our online resources. As such we will support new contributors in this process. When a new pull request is submitted by someone we will do the following: + +* Evaluate the contributors background if that is possible. If this is their first pull request submitted through a sprint, then support them in their efforts by pointing out CI and provide specific line-by-line feedback. +* If fixes to the existing pr are straight forward, the reviewer can "suggest inline changes" on the pull request by highlighting 1 or more modified lines, and suggesting edits in place. This approach of inline suggestions, is often a quick way to integrate feedback from a review +* If fixes to the existing PR are more involved, clearly articulate what is wrong in the pull request, and ask the contributor if they feel comfortable addressing it. If they don't, then someone in the core pyOpenSci team can support them in getting their pull request edited, reviewed and merged. + +The above process is often implemented on a case by case basis depending on the contributors background. + +:::{todo} +Did we address these questions above?? + + +What are the expectations for an external contributor? +What should they have done locally? +Do we expect someone to have done all the wrangling with Ruby and Jekyll? +::: + +## Pull requests and Continuous Integration + +At the bottom of every pull request is the Continuous Integration (CI) block. This block contains a set of checks that pyOpenSci has setup. Each check will have a red X's or green check next to it. + +## Pre-commit hooks and pre-commit.ci bot + +pyOpenSci uses [pre-commit](https://pre-commit.com/) and the [precommit.ci bot](https://pre-commit.ci/) to style check our repositories. This ensures our codebase remains clean, consistent, and free +from common errors. + +For all repositories we enable hooks that: + +* Look for extra spaces at the end of files +* Clean up trailing white space at the end of individual lines +* Check for spelling issues within the repository. + +For code repositories, we have several additional checks including: + +* Code format & style checks (e.g. black, isort) + +### About Pre-commit + +[Pre-commit](https://pre-commit.com/) is a framework for managing and +maintaining multi-language pre-commit hooks. It ensures that code follows +specified style and format rules before it gets committed to the repository. + +We generally use the following hooks: + +* **Autoformat**: Makes sure files end in a newline and only a newline. + - `end-of-file-fixer` +* **Lint**: Check for files with names that would conflict on a + case-insensitive filesystem like MacOS HFS+ or Windows FAT. + - `check-case-conflict` +* **Whitespace**: Clean up trailing white space at the end of individual lines. + - `trailing-whitespace` +* **Spelling**: Check for spelling issues within the repository. + - `codespell` + +Setting up pre-commit locally is optional because we have the pre-commit bot +setup in our CI workflows. However, if you are a pyOpenSci staff member regularly contributors, we suggest that you set it up locally in our repos to ensure +spell check errors (that the pre-commit ci bot can not fix in a pr) are addressed. + +### Setting Up Pre-commit Locally + +To set up pre-commit locally, follow these steps: + +1. **Install pre-commit** if it's not already installed on your computer. + + ```bash + pip install pre-commit + ``` +2. From the root of the pyOpenSci repository that you wish to run pre-commit +hooks on, run + + ```bash + pre-commit install + ``` +This will install all of the hooks that pyOpenSci has setup for that repository. +Most often there is a spell checker, and several markdown file formatters that +will remove excess white space. + + +3. To run pre-commit on all files in the repository - + + ```bash + pre-commit run --all-files + ``` + +4. pre-commit will run on all files that you modify + +pre-commit will run after you add and commit a change to the repository locally. +Sometimes you may need to override pre-commit - for example if you have a +spelling issue that you know is correct, but pre-commit thinks is wrong, you +may want to force commit that change and ask for help in the repo when you +open a pr. + +If you need to skip a local pre-commit check when you commit changes locally, +use: + + ```bash + git commit "commit message here" --no-verify + ``` + +### About the pre-commit CI Bot + +The [Pre-commit CI](https://pre-commit.ci/) bot is a continuous integration service that automatically +runs pre-commit hooks on each pull request. It also allows you to call the bot +to fix any issues with the pull request (with the exception of misspelled words). + +This helps maintain code quality +and consistency without requiring contributors to run pre-commit locally. + +[Learn more about pre-commit ci in our ci section here](pre-commit-ci) + +### Acknowledging New Contributors + +We use the [All-contributors bot](https://allcontributors.org/) to acknowledge +contributors across all of our GitHub repositories. Contributor information +is then published on [our website here](https://www.pyopensci.org/our-community/index.html#pyopensci-community-contributors). + +### Who we acknowledge +pyOpenSci is liberal in acknowledging all contributions large to small. When +someone new submits an issue or PR, add them as a contributor to the repo using +the bot. + +* It is ok if their name is already on our website as a contributor, +if this is their first contribution to a different repo, or a different type of contribution, add them. We will acknowledge the different types of contributions that our wonderful volunteers make. +* If they are already added as a contributor to the repo where the pull request is, that is ok too. The bot will inform you! + +To add a contributor - at the bottom of a pull request or an issue - call the +following command: + +`@all-contributors please add @kiersi for code, review` + +Replaceing `@kiersi` with `@contributors-username`. + +When you add a user, the bot will open a pull request that can be squashed +and merged. Once merged, their profile image and name will appear in the +README file of that repository. + + +pyOpenSci then has an automated build that will parse contributors across all of +our repos, adding them to +the contributor list and noting the type(s) of contributions that they have made +(e.g., packaging guide, peer review guide). + +:::{todo} +## GitHub & CI + +* Ci (Continuous integration) will be run on each new commit added to all of our public repositories (that have content). + + +### Permissions to run CI + +In general, things are setup so CI doesn’t run automagically for new contributors. Rather, someone with triage (?) rights will need to approve the workflow to run by hitting the approve and run button that will appear (see image below). We have things setup this way to avoid spam pr’s commits that will abuse our CI use. We could potentially adjust in the future - but also we could adjust but allowing more people with “access levels” that can approve CI. +::: diff --git a/community/index.md b/community/index.md index f838548..4eaa0f2 100644 --- a/community/index.md +++ b/community/index.md @@ -15,5 +15,4 @@ Slack :caption: GitHub Section GitHub -Our Repos ::: From 9ce2afba7d13f58cb771f8379bd246e96511eb59 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 17:03:51 -0600 Subject: [PATCH 02/52] Fix: add conditional for label name --- .github/workflows/add-help-wanted.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml index 9a11f66..79bf714 100644 --- a/.github/workflows/add-help-wanted.yml +++ b/.github/workflows/add-help-wanted.yml @@ -10,6 +10,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Add issue to project + if: contains(github.event.label.name, 'help-wanted') || contains(github.event.label.name, 'sprintable') id: add-to-project uses: actions/add-to-project@v1.0.1 with: From f83dce7fb9815c9c5f23fd7df318f55bde0013c8 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 17:07:49 -0600 Subject: [PATCH 03/52] Update add-help-wanted.yml --- .github/workflows/add-help-wanted.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml index 79bf714..39b412f 100644 --- a/.github/workflows/add-help-wanted.yml +++ b/.github/workflows/add-help-wanted.yml @@ -15,6 +15,7 @@ jobs: uses: actions/add-to-project@v1.0.1 with: project-url: https://github.com/orgs/pyOpenSci/projects/3 - github-token: ${{ secrets.GHPROJECT_TOKEN }} + # This is a organization level token so it can be used across all repos in our org + github-token: ${{ secrets.GHPROJECT_HELP_WANTED }} labeled: help-wanted, sprintable label-operator: OR From 4b7597fe2f6183227aa595e5ac54413c30d6b9ef Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 17:11:07 -0600 Subject: [PATCH 04/52] Update add-help-wanted.yml --- .github/workflows/add-help-wanted.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml index 39b412f..771b028 100644 --- a/.github/workflows/add-help-wanted.yml +++ b/.github/workflows/add-help-wanted.yml @@ -10,7 +10,6 @@ jobs: runs-on: ubuntu-latest steps: - name: Add issue to project - if: contains(github.event.label.name, 'help-wanted') || contains(github.event.label.name, 'sprintable') id: add-to-project uses: actions/add-to-project@v1.0.1 with: From 8c66e3cab466198ef4fa5ed26a99c8717bfd13e1 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 17:13:31 -0600 Subject: [PATCH 05/52] Fix: label name --- .github/workflows/add-help-wanted.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml index 771b028..aca8ff8 100644 --- a/.github/workflows/add-help-wanted.yml +++ b/.github/workflows/add-help-wanted.yml @@ -16,5 +16,5 @@ jobs: project-url: https://github.com/orgs/pyOpenSci/projects/3 # This is a organization level token so it can be used across all repos in our org github-token: ${{ secrets.GHPROJECT_HELP_WANTED }} - labeled: help-wanted, sprintable + labeled: help wanted, sprintable label-operator: OR From 5756f7a063eefccdbf36af031478f06f0489a17d Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 15:48:36 -0600 Subject: [PATCH 06/52] Add: github repo overview to the handbook --- community/github/intro.md | 11 +++++ community/github/our-repositories.md | 72 ++++++++++++++++++++-------- community/index.md | 1 - 3 files changed, 64 insertions(+), 20 deletions(-) diff --git a/community/github/intro.md b/community/github/intro.md index cc9a4d1..dea07a9 100644 --- a/community/github/intro.md +++ b/community/github/intro.md @@ -11,3 +11,14 @@ pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci proc * website content * tools that track contributors and keep the website up to date * peer review + +This section of the guidebook discusses our GitHub organization and processes +for adding and managing content and infrastructure across the organization. + + +:::{toctree} +:glob: +:maxdepth: 2 + +* +::: diff --git a/community/github/our-repositories.md b/community/github/our-repositories.md index 0aa379a..b60744d 100644 --- a/community/github/our-repositories.md +++ b/community/github/our-repositories.md @@ -1,13 +1,11 @@ -# Our Repositories +# pyOpenSci GitHub Repositories :::{todo} Add repositories from the pyOpenSci organization. ::: -## pyOpenSci GitHub Repository Overview - pyOpenSci manages multiple GitHub repositories to support various community -activities. Below is a description of each core repository. +activities. Below is a description of each repository. ### [Software-review Repository](https://www.pyopensci.org/software-peer-review/) @@ -22,33 +20,60 @@ any changes. This template's data are processed by a Python workflow, and even small modifications could disrupt the language processing. ::: +## Software-peer-review Guidebook Repository -### Software-peer-review Guidebook Repository - -This repository hosts our [software peer review guide](https://www.pyopensci.org/software-peer-review/), -which includes instructions and guidelines for authors, editors, the editor in -chief, and the peer review triage team. It also details our peer review policies, +This repository hosts our [software peer review guidebook](https://www.pyopensci.org/software-peer-review/), +which documents the processes and guidelines for authors, editors, the editor in +chief, and the peer review triage team as they manage our open peer review process. It also details our peer review policies, partnerships, and the templates used in the review process. -### Python-package-guide Repository +## Python-package-guide Repository The [python-package-guide repository](https://www.pyopensci.org/python-package-guide/) contains our community-developed guidelines and tutorials on Python packaging. -These resources are beginner-friendly and reflect best practices. +These resources are beginner-friendly and reflect Python packaging best practices. -### [pyosMeta Repository](https://github.com/pyOpenSci/pyosMeta) +## [pyosMeta Repository](https://github.com/pyOpenSci/pyosMeta) -The pyosMeta repo contains a Python package published on PyPI that tracks our +The pyosMeta repository contains a Python package published on PyPI that we use to track our package review and contributor data. This data is used in a GitHub action to update our website. -### [pyopensci.github.io Repository](https://github.com/pyOpenSci/pyopensci.github.io) +:::{todo} +Add more information about the contributor data workflow ... +::: + +## [pyopensci.github.io Repository](https://github.com/pyOpenSci/pyopensci.github.io) -Our website, [pyOpenSci](https://www.pyopensci.org/), is hosted on GitHub and -uses the Jekyll Minimal Mistakes theme. The python packages page, contributor page and peer review team page are all updated automagically using a -GitHub action workflow that is supported by the pyosMeta Python package. The workflow runs every other week but can be triggered manually as a **workflow +This repository contains code and content that builds and publishes our pyOpenSci website. The website, [pyOpenSci](https://www.pyopensci.org/), is hosted on GitHub and +uses the Jekyll Minimal Mistakes theme. The Python packages page, contributor page and peer review team page are all updated automagically using a +GitHub action workflow that is supported by the pyosMeta Python package discussed above. The workflow runs every other week but can be triggered manually as a **workflow dispatch**. +### Critical CI workflows in this repository + +The [contributor workflow action](https://github.com/pyOpenSci/pyopensci.github.io/blob/main/.github/workflows/update-contribs-reviews.yml) is a custom GitHub +action that is used to update the following website pages: + +* contributor page +* package listing page +* editorial, advisory council and executive council listing + +It runs as a cron job every other week but also can be run manually as a workflow +dispatch. If you need to update our package listing or contributor list on +the fly, please run this action. + +The action will: + +1. parse through all of our accepted pyOpenSci packages +2. collect package names, authors, reviewers and editors +3. collect metadata for the packages authors reviewers and editors using the GitHub (REST) API +4. Create 2 output YAML files discussed below. + +The yaml output files and then used to populate content on the website. + +### Metadata stored in this repository + 1. **Packages.yml**: Updates the [Python Packages page](https://www.pyopensci.org/python-packages.html) by parsing reviews from software-review repository issues. 2. **Contributors.yml**: Updates the [Our Community page](https://www.pyopensci.org/our-community/index.html) @@ -59,7 +84,16 @@ Update the website contributors guide with general CI and specific Jekyll information. ::: +## [pyOpenSci Sphinx Theme](https://github.com/pyOpenSci/pyos-sphinx-theme) + +**Platform:** Sphinx book template that builds on top of the pydata_sphinx_theme + +All of our pyOpenSci sphinx books (Handbook, packaging guide, software review guide ) have been customized to match our pyOpenSci branding. This repo contains the start of a sphinx theme that will incorporate all of our branding so we do not have to manually apply the branding and update the branding individually in each repo. Rather we can update branding in the theme and it will be applied across all of our repositories that use the theme. + +Creating a theme was inspired by Chris Holdgraf's 2i2c Sphinx theme. + ## [Handbook Repository](https://github.com/pyOpenSci/handbook) -The handbook repository hosts content that helps the community navigate our -online resources and communication channels. +**Platform:** Sphinx book running the pydata_sphinx_theme + +This is where we store our organization governance, code of conduct and processes around how we operate as an organization. diff --git a/community/index.md b/community/index.md index f838548..4eaa0f2 100644 --- a/community/index.md +++ b/community/index.md @@ -15,5 +15,4 @@ Slack :caption: GitHub Section GitHub -Our Repos ::: From 60f2de797c8595b780de390b2cfc8098ad47bbfa Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 15:51:30 -0600 Subject: [PATCH 07/52] Fix: add pyosPackage repo to list --- community/github/our-repositories.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/community/github/our-repositories.md b/community/github/our-repositories.md index b60744d..9dbc5b9 100644 --- a/community/github/our-repositories.md +++ b/community/github/our-repositories.md @@ -97,3 +97,10 @@ Creating a theme was inspired by Chris Holdgraf's 2i2c Sphinx theme. **Platform:** Sphinx book running the pydata_sphinx_theme This is where we store our organization governance, code of conduct and processes around how we operate as an organization. + +## [pyosPackage repository](https://github.com/pyOpenSci/pyosPackage) + +The pyosPackage repo contains an example pure-Python package that compliments +our package guide & tutorials. We will build this package example out over time +for folks that just want to see a working package without creating one +themselves. From 9a1d74c78d3d62d699a28398b6c0b440efa692ef Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 16:57:22 -0600 Subject: [PATCH 08/52] Fix: edits from @kiersi Co-authored-by: Jesse Mostipak --- community/github/intro.md | 2 +- community/github/our-repositories.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/community/github/intro.md b/community/github/intro.md index dea07a9..d9b0538 100644 --- a/community/github/intro.md +++ b/community/github/intro.md @@ -12,7 +12,7 @@ pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci proc * tools that track contributors and keep the website up to date * peer review -This section of the guidebook discusses our GitHub organization and processes +This section of the guidebook discusses our GitHub organization, and processes for adding and managing content and infrastructure across the organization. diff --git a/community/github/our-repositories.md b/community/github/our-repositories.md index 9dbc5b9..f11674b 100644 --- a/community/github/our-repositories.md +++ b/community/github/our-repositories.md @@ -23,8 +23,8 @@ small modifications could disrupt the language processing. ## Software-peer-review Guidebook Repository This repository hosts our [software peer review guidebook](https://www.pyopensci.org/software-peer-review/), -which documents the processes and guidelines for authors, editors, the editor in -chief, and the peer review triage team as they manage our open peer review process. It also details our peer review policies, +which documents the processes and guidelines for authors, editors, the Editor in +Chief, and the peer review triage team as they manage our open peer review process. It also details our peer review policies, partnerships, and the templates used in the review process. ## Python-package-guide Repository @@ -46,7 +46,7 @@ Add more information about the contributor data workflow ... ## [pyopensci.github.io Repository](https://github.com/pyOpenSci/pyopensci.github.io) This repository contains code and content that builds and publishes our pyOpenSci website. The website, [pyOpenSci](https://www.pyopensci.org/), is hosted on GitHub and -uses the Jekyll Minimal Mistakes theme. The Python packages page, contributor page and peer review team page are all updated automagically using a +uses the [Jekyll Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/) theme. The Python packages page, contributor page and peer review team page are all updated automagically using a GitHub action workflow that is supported by the pyosMeta Python package discussed above. The workflow runs every other week but can be triggered manually as a **workflow dispatch**. @@ -70,7 +70,7 @@ The action will: 3. collect metadata for the packages authors reviewers and editors using the GitHub (REST) API 4. Create 2 output YAML files discussed below. -The yaml output files and then used to populate content on the website. +The YAML output files and then used to populate content on the website. ### Metadata stored in this repository @@ -88,9 +88,9 @@ information. **Platform:** Sphinx book template that builds on top of the pydata_sphinx_theme -All of our pyOpenSci sphinx books (Handbook, packaging guide, software review guide ) have been customized to match our pyOpenSci branding. This repo contains the start of a sphinx theme that will incorporate all of our branding so we do not have to manually apply the branding and update the branding individually in each repo. Rather we can update branding in the theme and it will be applied across all of our repositories that use the theme. +All of our pyOpenSci Sphinx books (handbook, packaging guide, software review guide ) have been customized to match our pyOpenSci branding. This repo contains the start of a Sphinx theme that will incorporate all of our branding, so we do not have to manually apply the branding and update it individually in each repo. Instead, we can update branding in the theme and it will be applied across all of our repositories that use the theme. -Creating a theme was inspired by Chris Holdgraf's 2i2c Sphinx theme. +Creating a theme was inspired by [Chris Holdgraf's](https://chrisholdgraf.com/) 2i2c Sphinx theme. ## [Handbook Repository](https://github.com/pyOpenSci/handbook) @@ -100,7 +100,7 @@ This is where we store our organization governance, code of conduct and processe ## [pyosPackage repository](https://github.com/pyOpenSci/pyosPackage) -The pyosPackage repo contains an example pure-Python package that compliments +The pyosPackage repo contains an example pure-Python package that complements our package guide & tutorials. We will build this package example out over time for folks that just want to see a working package without creating one themselves. From b8e7eda0262f059b87b05c9779cbaf566800921b Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Thu, 30 May 2024 17:15:10 -0600 Subject: [PATCH 09/52] Add: sprint process to handbook --- community/events/intro.md | 56 ++++++++ community/events/sprints.md | 264 ++++++++++++++++++++++++++++++++++++ community/index.md | 10 ++ 3 files changed, 330 insertions(+) create mode 100644 community/events/intro.md create mode 100644 community/events/sprints.md diff --git a/community/events/intro.md b/community/events/intro.md new file mode 100644 index 0000000..a6eb3ec --- /dev/null +++ b/community/events/intro.md @@ -0,0 +1,56 @@ +# Meetings & Events + +## pyOpenSci meetings + +pyOpensci staff regularly attend community meetings (e.g. SciPy meeting, PyCon US, etc). If the meeting is in person, some of the staff may be in person at the event while the community manager / others might be supporting the event remotely. + +In these instances asynchronous communication and sharing of documents in an organized way is critical. + +### Event documents +For every meeting, pyOpenSci staff should create a Google drive folder located in our pyos-shared drive where meeting documents are stored. These documents may include talk and workshop proposals, attendee signup lists, graphics use in social media and out reach posts and more content related to the event. + +Before an event, pyOpenSci staff will make sure this folder is shared and supporting documents are added to it. Often the folder will be created prior to the event to store talk, Bof (birds of a feather), townhall and workshop proposals. + +:::{admonition} Team checkin prior to an event +:class: note + +Staff should also have a short check-in prior to an event to ensure that all documents, and elements needed for the event are shared, in the right place, etc. + +Because the internet might be an issue sometimes at an event, whomever is leading the event should always bring a pen and paper. +::: + +## Event social media and graphics + +The community manager will manage online “coms” and social media during an event. However it will be important for whomever is attending the event in person to be in asynchronous communication via the pyOpenSci Slack about key activities, findings, new cool things, etc to be posting about, promoting and highlighting. + +In some cases an event might “pop up” last minute - such as an Open Space at pyCon. In this case, the person attending the event may want to modify and reuse graphics posted on social media to publicize the event. + +To support this case, we should also create an event folder in our online graphics platform, Canva (our online graphics platform). This event specific folder will be where we store all graphics used to promote an event both before during and after in one place. This will make it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event or change in plans, as needed. + +:::{admonition} Share the Canva folder with the pyopensci-canva-team +:class: important + +Be sure to share the Canva folder with the `pyOpensci-canva-team` on Canva to ensure that the entire team has edit access to the graphics and can make last minute changes as needed! +Please also be sure to name files using expressive words that make them easy to find / use / reuse. +::: + +**ADD IMAGE** + +Image showing a pycon-24 folders in canva for an event. You can share the entire folder with the team to ensure the team has access to all of the contents inside. + +### Preparation prior to an event + +Prior to a, in-person sprint, you should have the following things created: + +1. A template "sign up" form with data fields that we collect from participants. This allows us to track who attends and event and to followup with them after (if they wish to have communication with us after) +1. A tabletop “card” that says pyOpenSci. You will need 2-3 cards on hand for any event in case participants are spread across a few tables. This card will be important for events like sprints, workshops and open spaces where pyOpenSci has one or more tables in a large room. It will signal to contributors that we are there and help people quickly find us. + * The card should have a qr code that is dynamic (so we can update the url that it points to). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank message to each participant using a mail-merge system. + +:::{todo} +will this work for events as we will want an event name associated with it but it would be annoying to make a new card for every event? UNLESS we make a bunch at once for all events for the year? + +And maybe a banner for a door if I'm running a workshop? +the table top thing looks like this: https://www.officedepot.com/a/products/5760240/American-Metalcraft-Stainless-Steel-Harp-Style/ (this is better than acrylic because it won't break, but we could do plastic if you prefer). + +we'd then print out (and laminate?) some kind of card that has the pyOpenSci logo, website, and a QR code that links to all of our socials//mailing list. this way it'll give people a visual cue as to where pyOS is congregating, as well as the option to interact with us directly. +::: diff --git a/community/events/sprints.md b/community/events/sprints.md new file mode 100644 index 0000000..6e7e503 --- /dev/null +++ b/community/events/sprints.md @@ -0,0 +1,264 @@ +# pyOpenSci sprints + +* TODO: https://github.com/actions/add-to-project?tab=readme-ov-file i think we want to set this up for all repos so this works for scipy. + +## What is a sprint? +A sprint is an open session where contributors come together to contribute to an open source project. Contributors may range from beginners, who are new to sprints, GitHub, and git, to experienced developers. Below we review how pyOpenSci runs sprints. + +There are three types of pyOpenSci sprint events: + +1. **Community Sprint Events**: pyOpenSci hosts these at meetings it attends, such as PyCon US and the SciPy meeting. +2. **Online Sprint Events**: pyOpenSci may hold its own sprint events online to encourage global contributions. +3. **Community-Hosted Sprint Events**: Contributors and community members host pyOpenSci sprint events at meetings they attend. + +During pyOpenSci sprints, contributors need tasks that are “sprintable.” +Sprintable tasks are those that can be worked on and potentially completed (or +partially completed) in a single sitting, whether that time is a half-day or a full day. + +Sprints can span 1-4 days but are most often 1-2 days long. + +### Tracking sprint contributions +Sprints often result in numerous pull requests and issues being opened by contributors. It’s important for pyOpenSci to track information around: + +* who is attending, +* where they are from (country, state etc) and +* what contributions they make. + +This information will support pyOpenSci's community impact and support and be +beneficial when we write grants and solicit sponsorships. + +#### How we track sprint outcomes +pyOpenSci tracks issues and pull requests created through community events using project boards. More on project board use is below. We track participation metrics +using _____ TODO MORE HERE ____ + +#### pyOpenSci sprints are accessible + +It's important to pyOpenSci's mission that sprints are accessible to both new +and seasoned contributors. We aim to ensure that all participants have a +successful experience with our community. Some participants are new and are +submitting their first-ever issue and/or pull request to an open source project. +These participants may need help using git and GitHub, or they may feel +intimidated by their first contribution. Others are more experienced and +comfortable in a sprint environment but may have questions about more technical +open issues and the outcomes that pyOpenSci wants to see for issue solutions. +Supporting all of these participants is crucial to our mission and can require +significant effort during a sprint event. + +As such, it's important for anyone leading a sprint to come prepared! + +### Sprint Participant Motivations + +Sprint participants are often motivated by different things: + +* Some come to learn. +* Some come to help and support a project they care about. +* Some come to connect and build community. + +pyOpenSci supports and empowers all of these motivations, with an emphasis on +empowering contributors who are newer to contributing while greatly benefiting +from more experienced sprinters who can help move the organization forward. + + +### Sprint Infrastructure - GitHub Project Boards + +To efficiently manage and track contributions during sprints, pyOpenSci utilizes +GitHub project boards. These boards help us organize tasks that participants can work on. This ensures that +contributors, whether new or experienced, can easily find and work on tasks +that suit their skills and interests. They also are used to track new contributions that we get during an event. + +#### Help-Wanted Board + +The pyOpenSci **Help-Wanted project board** is a organization level GitHub project board that provides a central place where contributors can +find tasks that pyOpenSci needs help with. We have two automated workflows setup +for the help-wanted project board: + +* Any issue or pull request with the `help-wanted` label is automatically added to this board. +* When an issue or pull request is closed, it is automatically archived from the project board. + +Tasks on this board are ideally smaller, well-defined, and can be completed or significantly advanced within the +duration of a sprint. The pyOpenSci Help-Wanted board is continuously updated to reflect +the current needs of pyOpenSci projects, making it easier for contributors to +jump in and start contributing. + +#### Annual Sprint Project Board + +At the start of each year, the pyOpenSci community manager creates a new Sprint +GitHub Project Board. The board will have several columns or statuses each or wchih represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: + +* **Track issues and pull requests opened during a sprint event** +* **Organize and Monitor Tasks**: Keep track of the progress of tasks during the sprint, ensuring clarity on which issues are being worked on and by whom. +- **Manage the Triage Process**: Keep track of which pull requests have been addressed and merged and which ones still need attention. +- **Calculate metrics**: Provide counts of activity that has occurred during a sprint event. + +By using these boards, pyOpenSci ensures that sprints are organized, efficient, +and accessible to all participants. + +### Year Round Sprint tasks + +Below are tasks to stay on top of throughout the year. By working on +these items as they pop up, you are saving time spent in preparing for a sprint. + +#### Maintain the the pyOpenSci help-wanted project board + +pyOpenSci uses the GitHub [help-wanted project board](https://github.com/orgs/pyOpenSci/projects/3) +to keep track of tasks that volunteers can assist with. When you see an issue +opened or if you open an issue yourself in any of our GitHub repositories within +our [pyOpenSci GitHub organization](https://www.github.com/pyopensci), always +consider whether the issue is something that someone else could help us with. + +If the issue is something that someone else in the community could do: + +1. **Add a `help-wanted` Label**: Any issue or pull request with the `help-wanted` + label in our organization will be automatically added to our [pyOpenSci + help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). + +2. **Add a `sprintable` Label (if applicable)**: If the task could be completed + during a sprint (meaning it is something that could be completed within an + hour and up to a single day's worth of work), also add the label `sprintable` + to the issue. + +3. **Update the Status on the Project Board**: Once the issue has been added to + the project board (it normally takes our CI workflow 30 seconds to a minute), + update the status of the issue on the project board based on the type of skill + needed. + + +The current types of tasks in our board include: + + * Python packaging + * Beginner friendly / non technical + * Dev Ops / GitHub actions (Continuous Integration) + * Python programming + * Website - css or ruby + +:::{todo} +we should add content review and sphinx as a status options for people that review our guidebook, run through tutorials etc. +::: + +:::{important} +If you are creating a new `help-wanted` issue it's critical that you include as much detailed information in the issue as possible. Imagine someone else reading the issue (that is not you!). In reading the issue, does an outside contributor have: + +* clearly understand the problem? (be specific, provide examples, links etc) +* have enough information to solve the problem? +* know exactly where the problem is occurring (provide links if you can or code examples ) +* have enough information needed to solve the problem? + +When in doubt, more information is always better! +::: + +Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a Sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. + +### Pre-Sprint Event Tasks + +#### Triage (Help-Wanted) Issues Across the pyOpenSci Organization + +Before a sprint begins, someone on the pyOpenSci team should go through and +triage all of the open issues in the organization to determine: + +* Whether some of them are sprintable. +* Whether they have enough specific and detailed information for someone to work + on the issue without too much help during a sprint. + +This could be a small team exercise at a pre-meeting event held online for +pyOpenSci staff and sprint community members (if there are any contributors +participating). + +The information found in the body of an issue is critical to running an effective +sprint. If the issue has very specific information that gives a potential +contributor everything they need to know to begin working, they will have fewer +questions during the sprint. If you have a table of 10-20 people sprinting for +pyOpenSci, this means the person running the sprint will have less to do on-site! +Sprints are busy—please add as much specific information as you can to each issue! + +#### THIS LIKELY WON'T WORK Ensure issue and pull request templates are up to date + +A challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues and pr's, during an event, every pyOpenSci GitHub repository should have a sprint issue and pull request template. Adding this template only needs to be completed once, however +if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a template. + +The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a workflow on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. + +NOTE - i'm not sure this will work. i forgot that pr templates are not as straight forward as issue templates are. issue templates are easier. + +### Tasks during a sprint + +Below are tasks that should occur during a spring event. + +#### Collect participant information + +The person running the event should collect information from participants +at the event via ______ **TODO insert how we do that here** _____. + +* dynamic qr code... that people can scan. with small table top signs? +* what do we collect? +* how do they opt out of future coms? + + +Metrics – +Number of pr’s +Number of issues +Who contributed +Where are the contributors from (country, place of work, other things??) + +### Update the sprint issue and pull request board + +During the event, the remote sprint support team (either community manager or a volunteer) , should + +* label all issues and pull requests as `sprint-event` and with the label for the event - e.g. `pyconus-24` as they are opened. +* Once that the sprint-event label is applied to an issue or pr, they with automatically be added to the project sprint board. +* Finally, once on the sprint board, they can then move each issue and pull request to the event name status on the sprint board. + +This process, if done during the sprint, will make triaging issues and pull requests after the event, easier. + +:::{todo} +We create one issue and pr template that we can use across all our repos – it has a label that automatically will be added to the board with “no status” +Jesse adds a label for the event and moves it to a column +::: + +### Review and triage pull requests and issues + +If you see small pull requests coming in that are clearly fixing things in a guidebook, please review them and approve if that makes sense. If +you see an issue opened that makes sense to work on, feel free to comment on it. + + + +All-contributors bot +Tagging issues and pr’s with sprint / event name +Creating a project board for sprint events +Writing this all up (let’s test drive for scipy) +Help for sprint event triage after the event +Event outputs +Blog post(s) +Social +Welcome new ppl to slack +Community Content “owners” +Related to above - help post event. We have a lot of issues and pr’s now. Can the community help with triage? + +### After a sprint + +* Followup with participants +* Send out an email thanking people after +* invite them to stay in touch / follow newsletter / follow linkedin, + + +## Meeting Metrics that pyOpenSci collects + +* Number of pr’s +* Number of issues +* Who contributed + * Where are the contributors from (country, place of work, other things??) + +:::{todo} +SPRINTS: Collecting information during - sprints, etc - process so we can work together? +GDPR compliant database +Attendees - where do we keep this info? +Name +State / country +Company / org? (Affiliation) +Email address +GH username +Domain(s) of expertise +Survey data +Current role +Workshops attended +Social handles +::: diff --git a/community/index.md b/community/index.md index 4eaa0f2..7cd529d 100644 --- a/community/index.md +++ b/community/index.md @@ -16,3 +16,13 @@ Slack GitHub ::: + + +:::{toctree} +:hidden: +:caption: pyOpenSci Events + +Events +pyOpenSci Sprints + +::: From 5bb150d00a5782a0d6638176a9ef2a3b26c974b9 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 12:24:05 -0600 Subject: [PATCH 10/52] Fix: more edits --- community/events/sprints.md | 75 ++++++++++++++++++++++++++++++++----- 1 file changed, 65 insertions(+), 10 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index 6e7e503..f9b90c9 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -2,6 +2,17 @@ * TODO: https://github.com/actions/add-to-project?tab=readme-ov-file i think we want to set this up for all repos so this works for scipy. +:::{admonition} TLDR +* summary here?? + +During sprint + +* label all issues as sprint-event, sprint-name-year +* merge small pr's that are clearly typo fixies, easy to review things +* add contributors as contributors to the repo using the all contributors bot @all-contributors add @githubusername for code, review (for an issue use review for a pr use code, review ). Merge each all contributor pr individually and immediately to avoid merge conflicts +::: + + ## What is a sprint? A sprint is an open session where contributors come together to contribute to an open source project. Contributors may range from beginners, who are new to sprints, GitHub, and git, to experienced developers. Below we review how pyOpenSci runs sprints. @@ -219,12 +230,62 @@ Jesse adds a label for the event and moves it to a column If you see small pull requests coming in that are clearly fixing things in a guidebook, please review them and approve if that makes sense. If you see an issue opened that makes sense to work on, feel free to comment on it. +## Acknowledge spring contirbutors - All-Contributors Bot + +pyOpenSci uses the [All-Contributors bot](https://allcontributors.org/docs/en/bot/usage) +to recognize and celebrate the contributions of all our contributors. This bot +helps automate the process of adding contributors to the repository, making it +easier to maintain accurate records of everyone's efforts. + +To add contributors to the repository using the All-Contributors bot: + +1. **Use the Bot Command**: In a comment on an issue or pull request, use the following command to add a contributor as follows. + `@all-contributors add @githubusername for ` + + if they have opened an issue only, or reviewed an open pr use: + + `@all-contributors add @githubusername for review` + if they have opened a pull request use: + `@all-contributors add @githubusername for code, review` + + +2. **Merge PRs Individually**: The bot will create a pull request to update the +contributors list. Merge each All-Contributors PR individually and immediately +to avoid merge conflicts. + +By recognizing contributors for their efforts, we foster a positive and inclusive +community, encouraging more participation and collaboration. + +## After a Sprint is complete + +After a sprint, we will follow up with participants to show our appreciation +and encourage continued engagement with the pyOpenSci community. Here are the key +steps to take: + +1. **Send a Thank You Email**: Send an email to all sprint participants thanking them for their contributions. Express gratitude for their time and effort, highlighting any significant achievements or milestones reached during the sprint. + +2. **Provide Feedback**: Include any relevant feedback or outcomes from the sprint. This could involve sharing metrics, such as the number of issues closed, pull requests merged, or any specific contributions that stood out. + +3. **Invite Continued Engagement**: + - **Newsletter**: Encourage participants to subscribe to the pyOpenSci newsletter + to stay updated on future events, news, and opportunities. + - **LinkedIn**: Invite them to follow pyOpenSci on LinkedIn for professional updates + and community highlights. + - **GitHub**: Remind them to continue following and contributing to pyOpenSci + repositories on GitHub. + - Discourse? + +4. **Stay Connected**: + - **Upcoming Events**: Inform participants about upcoming sprints, webinars, + workshops, or any other events they might be interested in. + +By taking these steps, you help maintain the momentum generated during the sprint, +foster a sense of community, and encourage ongoing contributions to pyOpenSci projects. + + + -All-contributors bot -Tagging issues and pr’s with sprint / event name -Creating a project board for sprint events -Writing this all up (let’s test drive for scipy) Help for sprint event triage after the event Event outputs Blog post(s) @@ -233,12 +294,6 @@ Welcome new ppl to slack Community Content “owners” Related to above - help post event. We have a lot of issues and pr’s now. Can the community help with triage? -### After a sprint - -* Followup with participants -* Send out an email thanking people after -* invite them to stay in touch / follow newsletter / follow linkedin, - ## Meeting Metrics that pyOpenSci collects From d09ba64eef23fd4603827722115e41d6320bf453 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 13:00:56 -0600 Subject: [PATCH 11/52] Fix: finish up sprint overview page --- community/events/intro.md | 10 +- community/events/sprints.md | 178 +++++++++++++++++++++++------------- 2 files changed, 115 insertions(+), 73 deletions(-) diff --git a/community/events/intro.md b/community/events/intro.md index a6eb3ec..6dbd38b 100644 --- a/community/events/intro.md +++ b/community/events/intro.md @@ -25,7 +25,7 @@ The community manager will manage online “coms” and social media during an e In some cases an event might “pop up” last minute - such as an Open Space at pyCon. In this case, the person attending the event may want to modify and reuse graphics posted on social media to publicize the event. -To support this case, we should also create an event folder in our online graphics platform, Canva (our online graphics platform). This event specific folder will be where we store all graphics used to promote an event both before during and after in one place. This will make it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event or change in plans, as needed. +To support this case, we should also create an event folder in our online graphics platform, Canva. This event specific folder will be where we store all graphics used to promote an event both before during and after in one place. This will make it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event or change in plans, as needed. :::{admonition} Share the Canva folder with the pyopensci-canva-team :class: important @@ -34,17 +34,13 @@ Be sure to share the Canva folder with the `pyOpensci-canva-team` on Canva to en Please also be sure to name files using expressive words that make them easy to find / use / reuse. ::: -**ADD IMAGE** - -Image showing a pycon-24 folders in canva for an event. You can share the entire folder with the team to ensure the team has access to all of the contents inside. - ### Preparation prior to an event -Prior to a, in-person sprint, you should have the following things created: +Prior to an, in-person sprint, you should have the following things created: 1. A template "sign up" form with data fields that we collect from participants. This allows us to track who attends and event and to followup with them after (if they wish to have communication with us after) 1. A tabletop “card” that says pyOpenSci. You will need 2-3 cards on hand for any event in case participants are spread across a few tables. This card will be important for events like sprints, workshops and open spaces where pyOpenSci has one or more tables in a large room. It will signal to contributors that we are there and help people quickly find us. - * The card should have a qr code that is dynamic (so we can update the url that it points to). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank message to each participant using a mail-merge system. + * The card should have a qr code that is dynamic (so we can update the url that it points to and reuse the cards). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank message to each participant using a mail-merge system. :::{todo} will this work for events as we will want an event name associated with it but it would be annoying to make a new card for every event? UNLESS we make a bunch at once for all events for the year? diff --git a/community/events/sprints.md b/community/events/sprints.md index f9b90c9..33e351c 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -1,15 +1,23 @@ # pyOpenSci sprints +:::{todo} * TODO: https://github.com/actions/add-to-project?tab=readme-ov-file i think we want to set this up for all repos so this works for scipy. +::: -:::{admonition} TLDR -* summary here?? +:::{admonition} TL;DR -During sprint +**Before sprint** +* Go through the pyOPenSci repo issues and ensure all relevant help-wanted / sprintable issues have labels and are on the project board. +* Also ensure all issues on the project board have enough specific information for a new user to follow and complete the task needed to be done. -* label all issues as sprint-event, sprint-name-year +**During sprint** + +* label all newly submitted issues as sprint-event, sprint-name-year * merge small pr's that are clearly typo fixies, easy to review things * add contributors as contributors to the repo using the all contributors bot @all-contributors add @githubusername for code, review (for an issue use review for a pr use code, review ). Merge each all contributor pr individually and immediately to avoid merge conflicts + +**After Sprint** + ::: @@ -31,18 +39,28 @@ Sprints can span 1-4 days but are most often 1-2 days long. ### Tracking sprint contributions Sprints often result in numerous pull requests and issues being opened by contributors. It’s important for pyOpenSci to track information around: -* who is attending, -* where they are from (country, state etc) and -* what contributions they make. +* Who is attending, +* Where they are from (country, state etc) and +* What contributions they make. This information will support pyOpenSci's community impact and support and be beneficial when we write grants and solicit sponsorships. -#### How we track sprint outcomes -pyOpenSci tracks issues and pull requests created through community events using project boards. More on project board use is below. We track participation metrics -using _____ TODO MORE HERE ____ +pyOpenSci uses a combination of GitHub project boards and user surveys to track participation and success metrics. More on that below. + +## Sprint Participant Motivations + +Sprint participants are often motivated by different things: -#### pyOpenSci sprints are accessible +* Some come to learn. +* Some come to help and support a project they care about. +* Some come to connect and build community. + +pyOpenSci supports and empowers all of these motivations, with an emphasis on +empowering contributors who are newer to contributing while greatly benefiting +from more experienced sprinters who can help move the organization forward. + +### pyOpenSci sprints are accessible It's important to pyOpenSci's mission that sprints are accessible to both new and seasoned contributors. We aim to ensure that all participants have a @@ -55,22 +73,10 @@ open issues and the outcomes that pyOpenSci wants to see for issue solutions. Supporting all of these participants is crucial to our mission and can require significant effort during a sprint event. -As such, it's important for anyone leading a sprint to come prepared! - -### Sprint Participant Motivations - -Sprint participants are often motivated by different things: - -* Some come to learn. -* Some come to help and support a project they care about. -* Some come to connect and build community. - -pyOpenSci supports and empowers all of these motivations, with an emphasis on -empowering contributors who are newer to contributing while greatly benefiting -from more experienced sprinters who can help move the organization forward. +As such, it's important for anyone leading a sprint to come prepared! In some cases having community helpers will go along way to supporting beginner contributor success. -### Sprint Infrastructure - GitHub Project Boards +## Sprint Infrastructure - GitHub Project Boards To efficiently manage and track contributions during sprints, pyOpenSci utilizes GitHub project boards. These boards help us organize tasks that participants can work on. This ensures that @@ -79,7 +85,7 @@ that suit their skills and interests. They also are used to track new contributi #### Help-Wanted Board -The pyOpenSci **Help-Wanted project board** is a organization level GitHub project board that provides a central place where contributors can +The pyOpenSci [**Help-Wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is a organization level GitHub project board that provides a central place where contributors can find tasks that pyOpenSci needs help with. We have two automated workflows setup for the help-wanted project board: @@ -87,22 +93,24 @@ for the help-wanted project board: * When an issue or pull request is closed, it is automatically archived from the project board. Tasks on this board are ideally smaller, well-defined, and can be completed or significantly advanced within the -duration of a sprint. The pyOpenSci Help-Wanted board is continuously updated to reflect -the current needs of pyOpenSci projects, making it easier for contributors to -jump in and start contributing. +duration of a sprint. The pyOpenSci Help-Wanted board should be updated throughout the year as new issues are opened in our organization GitHub repositories. Continual updates makes it easier for: + +* Contributors to jump in and start contributing and +* Sprint leaders to prepare for a sprint as the board will be more up to date. #### Annual Sprint Project Board At the start of each year, the pyOpenSci community manager creates a new Sprint -GitHub Project Board. The board will have several columns or statuses each or wchih represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: +GitHub Project Board. Here is an example of the [2024 sprint project board](https://github.com/orgs/pyOpenSci/projects/12). + +The board will have several columns or statuses each or which represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: * **Track issues and pull requests opened during a sprint event** * **Organize and Monitor Tasks**: Keep track of the progress of tasks during the sprint, ensuring clarity on which issues are being worked on and by whom. - **Manage the Triage Process**: Keep track of which pull requests have been addressed and merged and which ones still need attention. - **Calculate metrics**: Provide counts of activity that has occurred during a sprint event. -By using these boards, pyOpenSci ensures that sprints are organized, efficient, -and accessible to all participants. +By using these boards, pyOpenSci staff can easily keep tabs of sprint activities and outcomes. It also helps us ensure that all sprint issues and pull requests are addressed in a timely manner. ### Year Round Sprint tasks @@ -146,22 +154,23 @@ The current types of tasks in our board include: we should add content review and sphinx as a status options for people that review our guidebook, run through tutorials etc. ::: -:::{important} -If you are creating a new `help-wanted` issue it's critical that you include as much detailed information in the issue as possible. Imagine someone else reading the issue (that is not you!). In reading the issue, does an outside contributor have: +:::{admonition} Make sure issues contain specific detailed information before adding them to a project board +:class: important -* clearly understand the problem? (be specific, provide examples, links etc) -* have enough information to solve the problem? -* know exactly where the problem is occurring (provide links if you can or code examples ) -* have enough information needed to solve the problem? +If you are creating a new `help-wanted` issue, it's important to include as much detailed information in the issue as possible. Imagine someone else reading the issue (that is not you!). In reading the issue, does an outside contributor have: + +* enough information to understand the problem? (be specific, provide examples, links runnable code, broken github action runs) +* enough information to solve the problem? +* know exactly where the problem is occurring (provide links if you can or code examples) When in doubt, more information is always better! ::: Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a Sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. -### Pre-Sprint Event Tasks +## Pre-Sprint Event Tasks -#### Triage (Help-Wanted) Issues Across the pyOpenSci Organization +### Triage (Help-Wanted) Issues Across the pyOpenSci Organization Before a sprint begins, someone on the pyOpenSci team should go through and triage all of the open issues in the organization to determine: @@ -169,6 +178,7 @@ triage all of the open issues in the organization to determine: * Whether some of them are sprintable. * Whether they have enough specific and detailed information for someone to work on the issue without too much help during a sprint. +* Whether some open issues can be closed. This could be a small team exercise at a pre-meeting event held online for pyOpenSci staff and sprint community members (if there are any contributors @@ -181,23 +191,37 @@ questions during the sprint. If you have a table of 10-20 people sprinting for pyOpenSci, this means the person running the sprint will have less to do on-site! Sprints are busy—please add as much specific information as you can to each issue! -#### THIS LIKELY WON'T WORK Ensure issue and pull request templates are up to date +### Ensure issue and pull request templates are up to date -A challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues and pr's, during an event, every pyOpenSci GitHub repository should have a sprint issue and pull request template. Adding this template only needs to be completed once, however -if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a template. +A challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues, during an event, every pyOpenSci GitHub repository should have a sprint issue template. Adding this template only needs to be completed once. However, if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a sprint issue template. -The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a workflow on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. +The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a GitHub action on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. +:::{todo} +test this workflow: https://github.com/actions/add-to-project in a single repo NOTE - i'm not sure this will work. i forgot that pr templates are not as straight forward as issue templates are. issue templates are easier. +::: + +### Create a participant signup form + +* create the form +* create a dynamic qr code that we can update (the is placed on our table top cards ) OR get a card that we can add a sticker to with the code and replace the stickers... + + +:::{todo} + +jesse will develop this process with whatever platform we end up using... +::: + -### Tasks during a sprint +## Tasks during a sprint Below are tasks that should occur during a spring event. -#### Collect participant information +### Collect participant information The person running the event should collect information from participants -at the event via ______ **TODO insert how we do that here** _____. +at the event via ______ **TODO insert how we do that here** _____ following the process Jesse creates above.... * dynamic qr code... that people can scan. with small table top signs? * what do we collect? @@ -212,11 +236,11 @@ Where are the contributors from (country, place of work, other things??) ### Update the sprint issue and pull request board -During the event, the remote sprint support team (either community manager or a volunteer) , should +During the event, the remote sprint support team (either Community Manager or a volunteer), should: * label all issues and pull requests as `sprint-event` and with the label for the event - e.g. `pyconus-24` as they are opened. -* Once that the sprint-event label is applied to an issue or pr, they with automatically be added to the project sprint board. -* Finally, once on the sprint board, they can then move each issue and pull request to the event name status on the sprint board. +* Once that the `sprint-event` label is applied to an issue or pr, they with automatically be added to the project sprint board. +* Finally, once on the sprint board, they can then move each issue and pull request to the event name status on the sprint board. (this also can be done from the issue itself. ) This process, if done during the sprint, will make triaging issues and pull requests after the event, easier. @@ -227,10 +251,14 @@ Jesse adds a label for the event and moves it to a column ### Review and triage pull requests and issues -If you see small pull requests coming in that are clearly fixing things in a guidebook, please review them and approve if that makes sense. If -you see an issue opened that makes sense to work on, feel free to comment on it. +If you see small pull requests coming in that are clearly fixing things (typos, etc) in a guidebook, please review them and approve if that makes sense. If +you see an issue opened that makes sense to work on remotely with a participant, feel free to comment on it. -## Acknowledge spring contirbutors - All-Contributors Bot +:::{todo} +We will need to feel some of this out at scipy. +::: + +### Acknowledge sprint contributors - All-Contributors Bot pyOpenSci uses the [All-Contributors bot](https://allcontributors.org/docs/en/bot/usage) to recognize and celebrate the contributions of all our contributors. This bot @@ -239,24 +267,39 @@ easier to maintain accurate records of everyone's efforts. To add contributors to the repository using the All-Contributors bot: -1. **Use the Bot Command**: In a comment on an issue or pull request, use the following command to add a contributor as follows. +**Use the Bot Command**: In a comment on an issue or pull request, use the following command to add a contributor as follows. + `@all-contributors add @githubusername for ` - if they have opened an issue only, or reviewed an open pr use: +If they have opened an issue only, or reviewed an open pr use: `@all-contributors add @githubusername for review` - if they have opened a pull request use: + +If they have opened a pull request use: `@all-contributors add @githubusername for code, review` -2. **Merge PRs Individually**: The bot will create a pull request to update the -contributors list. Merge each All-Contributors PR individually and immediately -to avoid merge conflicts. +2. **Merge all-contributor bot Pull Requests Individually**: The bot will create a pull request to update the +contributors list when you call the commands above. IMPORTANT: Merge each all-Contributors bot pull request individually and immediately before adding another contributor to avoid merge conflicts. By recognizing contributors for their efforts, we foster a positive and inclusive community, encouraging more participation and collaboration. -## After a Sprint is complete +## After a Sprint tasks + +### Issue and PR triage +The biggest effort after a sprint will be triaging & addressing issues and pull requests that have been submitted during the sprint. This could take 1-2 weeks and up to a month depending on the scope of each change submitted. + +If there are new issues with no associated pull request, you can + +1. Invite the issue author to submit a pr if the change seems reasonable and they are up to the task. +2. If the issue is one that we agree should be addressed, then label the issue with `help-wanted` / `sprintable` so someone else can tackle it at our next pyOpenSci sprint. + +Review each pull request submitted (or invite community members to review) and determine if the pull request looks good as is or requires changes following the standard GitHub review process. + +Merge the pull request when it is complete and ready to be merged. + +### Followup thank you notes After a sprint, we will follow up with participants to show our appreciation and encourage continued engagement with the pyOpenSci community. Here are the key @@ -279,8 +322,8 @@ steps to take: - **Upcoming Events**: Inform participants about upcoming sprints, webinars, workshops, or any other events they might be interested in. -By taking these steps, you help maintain the momentum generated during the sprint, -foster a sense of community, and encourage ongoing contributions to pyOpenSci projects. +By thanking contributors you are helping to maintain the momentum generated during the sprint while also +fostering a sense of community, and encourage ongoing contributions to pyOpenSci projects. @@ -295,12 +338,15 @@ Community Content “owners” Related to above - help post event. We have a lot of issues and pr’s now. Can the community help with triage? -## Meeting Metrics that pyOpenSci collects -* Number of pr’s -* Number of issues -* Who contributed +:::{admonition} Meeting metrics that pyOpenSci collects +:class: info +* Number of pull request submitted +* Number of issues submitted +* Number of contributors contributed * Where are the contributors from (country, place of work, other things??) +::: + :::{todo} SPRINTS: Collecting information during - sprints, etc - process so we can work together? From 7fca20f007b43f8893619d7b39c1731dbd979da3 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 13:26:17 -0600 Subject: [PATCH 12/52] Edits from @kiersi Co-authored-by: Jesse Mostipak --- community/events/intro.md | 26 ++++++++++++++------------ community/events/sprints.md | 2 +- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/community/events/intro.md b/community/events/intro.md index 6dbd38b..afca5ee 100644 --- a/community/events/intro.md +++ b/community/events/intro.md @@ -4,28 +4,28 @@ pyOpensci staff regularly attend community meetings (e.g. SciPy meeting, PyCon US, etc). If the meeting is in person, some of the staff may be in person at the event while the community manager / others might be supporting the event remotely. -In these instances asynchronous communication and sharing of documents in an organized way is critical. +In these instances, asynchronous communication and sharing of documents in an organized way is critical. ### Event documents -For every meeting, pyOpenSci staff should create a Google drive folder located in our pyos-shared drive where meeting documents are stored. These documents may include talk and workshop proposals, attendee signup lists, graphics use in social media and out reach posts and more content related to the event. +For every meeting, pyOpenSci staff should create a Google Drive folder, located in our pyos-shared drive, where meeting documents will be stored. These documents may include talk and workshop proposals, attendee signup lists, graphics used in social media and outreach posts and more content related to the event. Before an event, pyOpenSci staff will make sure this folder is shared and supporting documents are added to it. Often the folder will be created prior to the event to store talk, Bof (birds of a feather), townhall and workshop proposals. :::{admonition} Team checkin prior to an event :class: note -Staff should also have a short check-in prior to an event to ensure that all documents, and elements needed for the event are shared, in the right place, etc. +Staff should also have a short check-in prior to an event to ensure that all documents, and elements needed for the event, are shared in the right place, appropriate permissions are granted, remote support needs for the event are clarified, etc. Because the internet might be an issue sometimes at an event, whomever is leading the event should always bring a pen and paper. ::: ## Event social media and graphics -The community manager will manage online “coms” and social media during an event. However it will be important for whomever is attending the event in person to be in asynchronous communication via the pyOpenSci Slack about key activities, findings, new cool things, etc to be posting about, promoting and highlighting. +The community manager will manage online “comms” and social media during an event. However, it is important for whomever is attending the event in person to be in asynchronous communication via the pyOpenSci Slack about key activities, findings, new cool things, etc. to be posting about, promoting and highlighting. -In some cases an event might “pop up” last minute - such as an Open Space at pyCon. In this case, the person attending the event may want to modify and reuse graphics posted on social media to publicize the event. +In some cases, an event might “pop up” last minute--such as an Open Space at PyCon. In this case, the person attending the event may want to modify and reuse graphics posted on social media to publicize the event. -To support this case, we should also create an event folder in our online graphics platform, Canva. This event specific folder will be where we store all graphics used to promote an event both before during and after in one place. This will make it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event or change in plans, as needed. +To support this case, an event folder in our online graphics platform, Canva, should be created prior to the event and shared with the pyOpenSci team. This event-specific folder will be where all graphics used to promote an event, both before, during and after, are stored. Using Canva as a central location for graphics makes it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event, notify of any change in plans, etc. as needed. :::{admonition} Share the Canva folder with the pyopensci-canva-team :class: important @@ -36,17 +36,19 @@ Please also be sure to name files using expressive words that make them easy to ### Preparation prior to an event -Prior to an, in-person sprint, you should have the following things created: +Prior to an in-person sprint, the following items should be created: -1. A template "sign up" form with data fields that we collect from participants. This allows us to track who attends and event and to followup with them after (if they wish to have communication with us after) +1. A template "sign up" form, created in HubSpot and shared via a bit.ly shortlink, with data fields that we collect from participants. This allows us to track who attends and event and to followup with them after (if they wish to have communication with us after) 1. A tabletop “card” that says pyOpenSci. You will need 2-3 cards on hand for any event in case participants are spread across a few tables. This card will be important for events like sprints, workshops and open spaces where pyOpenSci has one or more tables in a large room. It will signal to contributors that we are there and help people quickly find us. - * The card should have a qr code that is dynamic (so we can update the url that it points to and reuse the cards). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank message to each participant using a mail-merge system. + * The card should have a qr code that is dynamic (so we can update the url that it points to and reuse the cards). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank you message to each participant using MailChimp or HubSpot. :::{todo} will this work for events as we will want an event name associated with it but it would be annoying to make a new card for every event? UNLESS we make a bunch at once for all events for the year? -And maybe a banner for a door if I'm running a workshop? -the table top thing looks like this: https://www.officedepot.com/a/products/5760240/American-Metalcraft-Stainless-Steel-Harp-Style/ (this is better than acrylic because it won't break, but we could do plastic if you prefer). +We are currently pricing out a travel banner, to be used outside a space where pyOpenSci is running a workshop. +An example of the [base/holder for the table top card](https://www.officedepot.com/a/products/5760240/American-Metalcraft-Stainless-Steel-Harp-Style/). We'll initially test out metal, as they will be less likely to break in transit, however acrylic options are also available. -we'd then print out (and laminate?) some kind of card that has the pyOpenSci logo, website, and a QR code that links to all of our socials//mailing list. this way it'll give people a visual cue as to where pyOS is congregating, as well as the option to interact with us directly. +Cards will be designed and printed, all of which will contain, at minimum, the pyOpenSci logo, website address, and a QR code that links to all of our socials/mailing list. this way it'll give people a visual cue as to where pyOS is congregating, as well as the option to interact with us directly. + +Cards will be designed to be printed out on a home printer, or through MOO, and laminated when non-glossy paper is used. ::: diff --git a/community/events/sprints.md b/community/events/sprints.md index 33e351c..6e8c4e3 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -6,7 +6,7 @@ :::{admonition} TL;DR -**Before sprint** +**Before a sprint** * Go through the pyOPenSci repo issues and ensure all relevant help-wanted / sprintable issues have labels and are on the project board. * Also ensure all issues on the project board have enough specific information for a new user to follow and complete the task needed to be done. From e76b610220fcb66dc9f7055cf88bcfabbe7d1e6e Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 13:34:48 -0600 Subject: [PATCH 13/52] Fix: Edits from @kiersi Co-authored-by: Jesse Mostipak --- community/events/sprints.md | 58 +++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index 6e8c4e3..8031574 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -10,13 +10,15 @@ * Go through the pyOPenSci repo issues and ensure all relevant help-wanted / sprintable issues have labels and are on the project board. * Also ensure all issues on the project board have enough specific information for a new user to follow and complete the task needed to be done. -**During sprint** +**During a sprint** * label all newly submitted issues as sprint-event, sprint-name-year -* merge small pr's that are clearly typo fixies, easy to review things -* add contributors as contributors to the repo using the all contributors bot @all-contributors add @githubusername for code, review (for an issue use review for a pr use code, review ). Merge each all contributor pr individually and immediately to avoid merge conflicts +* merge small PRs that are clearly typo fixes and other easy to review things +* for PRs, add contributors to the repo using the all contributors bot, with the format `@all-contributors add @githubusername for code, review` +* for an issue use review for a pr use code, review ). +* merge each all contributor PR individually and immediately to avoid merge conflicts -**After Sprint** +**After a Sprint** ::: @@ -28,7 +30,7 @@ There are three types of pyOpenSci sprint events: 1. **Community Sprint Events**: pyOpenSci hosts these at meetings it attends, such as PyCon US and the SciPy meeting. 2. **Online Sprint Events**: pyOpenSci may hold its own sprint events online to encourage global contributions. -3. **Community-Hosted Sprint Events**: Contributors and community members host pyOpenSci sprint events at meetings they attend. +3. **Community-hosted Sprint Events**: Contributors and community members host pyOpenSci sprint events at meetings they attend. During pyOpenSci sprints, contributors need tasks that are “sprintable.” Sprintable tasks are those that can be worked on and potentially completed (or @@ -50,14 +52,14 @@ pyOpenSci uses a combination of GitHub project boards and user surveys to track ## Sprint Participant Motivations -Sprint participants are often motivated by different things: +Sprint participants are often motivated by different things. Some come to: -* Some come to learn. -* Some come to help and support a project they care about. -* Some come to connect and build community. +* learn +* help and support a project they care about +* connect and build community pyOpenSci supports and empowers all of these motivations, with an emphasis on -empowering contributors who are newer to contributing while greatly benefiting +empowering contributors who are newer to contributing, while greatly benefiting from more experienced sprinters who can help move the organization forward. ### pyOpenSci sprints are accessible @@ -85,7 +87,7 @@ that suit their skills and interests. They also are used to track new contributi #### Help-Wanted Board -The pyOpenSci [**Help-Wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is a organization level GitHub project board that provides a central place where contributors can +The pyOpenSci [**Help-Wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is an organization-level GitHub project board that provides a central place where contributors can find tasks that pyOpenSci needs help with. We have two automated workflows setup for the help-wanted project board: @@ -103,7 +105,7 @@ duration of a sprint. The pyOpenSci Help-Wanted board should be updated througho At the start of each year, the pyOpenSci community manager creates a new Sprint GitHub Project Board. Here is an example of the [2024 sprint project board](https://github.com/orgs/pyOpenSci/projects/12). -The board will have several columns or statuses each or which represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: +The board will have several columns or statuses, each of which represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: * **Track issues and pull requests opened during a sprint event** * **Organize and Monitor Tasks**: Keep track of the progress of tasks during the sprint, ensuring clarity on which issues are being worked on and by whom. @@ -121,22 +123,22 @@ these items as they pop up, you are saving time spent in preparing for a sprint. pyOpenSci uses the GitHub [help-wanted project board](https://github.com/orgs/pyOpenSci/projects/3) to keep track of tasks that volunteers can assist with. When you see an issue -opened or if you open an issue yourself in any of our GitHub repositories within +opened, or if you open an issue yourself in any of our GitHub repositories within our [pyOpenSci GitHub organization](https://www.github.com/pyopensci), always consider whether the issue is something that someone else could help us with. If the issue is something that someone else in the community could do: -1. **Add a `help-wanted` Label**: Any issue or pull request with the `help-wanted` +1. **Add a `help-wanted` Label**: any issue or pull request with the `help-wanted` label in our organization will be automatically added to our [pyOpenSci help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). -2. **Add a `sprintable` Label (if applicable)**: If the task could be completed +2. **Add a `sprintable` Label (if applicable)**: if the task could be completed during a sprint (meaning it is something that could be completed within an hour and up to a single day's worth of work), also add the label `sprintable` to the issue. -3. **Update the Status on the Project Board**: Once the issue has been added to +3. **Update the Status on the Project Board**: once the issue has been added to the project board (it normally takes our CI workflow 30 seconds to a minute), update the status of the issue on the project board based on the type of skill needed. @@ -148,13 +150,13 @@ The current types of tasks in our board include: * Beginner friendly / non technical * Dev Ops / GitHub actions (Continuous Integration) * Python programming - * Website - css or ruby + * Website - CSS or Ruby :::{todo} we should add content review and sphinx as a status options for people that review our guidebook, run through tutorials etc. ::: -:::{admonition} Make sure issues contain specific detailed information before adding them to a project board +:::{admonition} Make sure issues contain specific, detailed information before adding them to a project board :class: important If you are creating a new `help-wanted` issue, it's important to include as much detailed information in the issue as possible. Imagine someone else reading the issue (that is not you!). In reading the issue, does an outside contributor have: @@ -166,7 +168,7 @@ If you are creating a new `help-wanted` issue, it's important to include as much When in doubt, more information is always better! ::: -Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a Sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. +Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. ## Pre-Sprint Event Tasks @@ -193,7 +195,7 @@ Sprints are busy—please add as much specific information as you can to each is ### Ensure issue and pull request templates are up to date -A challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues, during an event, every pyOpenSci GitHub repository should have a sprint issue template. Adding this template only needs to be completed once. However, if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a sprint issue template. +One challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues during an event, every pyOpenSci GitHub repository should have a sprint issue template. Adding this template only needs to be completed once. However, if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a sprint issue template. The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a GitHub action on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. @@ -216,7 +218,7 @@ jesse will develop this process with whatever platform we end up using... ## Tasks during a sprint -Below are tasks that should occur during a spring event. +Below are tasks that should occur during a sprint event. ### Collect participant information @@ -229,7 +231,7 @@ at the event via ______ **TODO insert how we do that here** _____ following the Metrics – -Number of pr’s +Number of PRs Number of issues Who contributed Where are the contributors from (country, place of work, other things??) @@ -290,9 +292,9 @@ community, encouraging more participation and collaboration. ### Issue and PR triage The biggest effort after a sprint will be triaging & addressing issues and pull requests that have been submitted during the sprint. This could take 1-2 weeks and up to a month depending on the scope of each change submitted. -If there are new issues with no associated pull request, you can +If there are new issues with no associated pull request, you can: -1. Invite the issue author to submit a pr if the change seems reasonable and they are up to the task. +1. Invite the issue author to submit a PR if the change seems reasonable and they are up to the task. 2. If the issue is one that we agree should be addressed, then label the issue with `help-wanted` / `sprintable` so someone else can tackle it at our next pyOpenSci sprint. Review each pull request submitted (or invite community members to review) and determine if the pull request looks good as is or requires changes following the standard GitHub review process. @@ -310,19 +312,19 @@ steps to take: 2. **Provide Feedback**: Include any relevant feedback or outcomes from the sprint. This could involve sharing metrics, such as the number of issues closed, pull requests merged, or any specific contributions that stood out. 3. **Invite Continued Engagement**: - - **Newsletter**: Encourage participants to subscribe to the pyOpenSci newsletter + - **Newsletter**: Encourage participants to subscribe to the [pyOpenSci newsletter](https://eepurl.com/iM7SOM) to stay updated on future events, news, and opportunities. - - **LinkedIn**: Invite them to follow pyOpenSci on LinkedIn for professional updates + - **LinkedIn**: Invite them to follow [pyOpenSci on LinkedIn](https://www.linkedin.com/company/pyopensci) for professional updates and community highlights. - **GitHub**: Remind them to continue following and contributing to pyOpenSci - repositories on GitHub. + [repositories on GitHub](https://github.com/pyopensci). - Discourse? 4. **Stay Connected**: - **Upcoming Events**: Inform participants about upcoming sprints, webinars, workshops, or any other events they might be interested in. -By thanking contributors you are helping to maintain the momentum generated during the sprint while also +By thanking contributors you are helping to maintain the momentum generated during the sprint, while also fostering a sense of community, and encourage ongoing contributions to pyOpenSci projects. From 35dcd05e4b9b78b171524503fc9ac04590fef318 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 15:45:03 -0600 Subject: [PATCH 14/52] Fix: edits from review --- community/events/sprints.md | 103 ++++++++++++++++++++++-------------- conf.py | 4 +- 2 files changed, 66 insertions(+), 41 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index 8031574..b0a348c 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -1,4 +1,4 @@ -# pyOpenSci sprints +# pyOpenSci Sprints :::{todo} * TODO: https://github.com/actions/add-to-project?tab=readme-ov-file i think we want to set this up for all repos so this works for scipy. @@ -7,19 +7,24 @@ :::{admonition} TL;DR **Before a sprint** -* Go through the pyOPenSci repo issues and ensure all relevant help-wanted / sprintable issues have labels and are on the project board. -* Also ensure all issues on the project board have enough specific information for a new user to follow and complete the task needed to be done. + +* pyOpenSci staff go through the pyOpenSci repo issues and ensure all relevant **help-wanted** and/or **sprintable** both have appropriated labels and have been added to the the project board in the appropriate column (beginner-friendly, python, dev-ops/ci, Python, Sphinx). +* pyOpenSci staff ensure all issues on the project board have enough **specific** information for a new user to follow and complete the task needed to be done. The more specific the issue is, the fewer questions a sprinter / contributor will ask during a sprint. This saves significant time and energy for both the sprint attendee and whomever is leading the sprint. **During a sprint** -* label all newly submitted issues as sprint-event, sprint-name-year -* merge small PRs that are clearly typo fixes and other easy to review things -* for PRs, add contributors to the repo using the all contributors bot, with the format `@all-contributors add @githubusername for code, review` -* for an issue use review for a pr use code, review ). -* merge each all contributor PR individually and immediately to avoid merge conflicts +* Label all newly submitted issues as `sprint-event`, `sprint-name-year` (example: `sprint`, `pyconus-24`) +* Merge small PRs that are clearly mergeable without significant review. Examples might include: typo fixes and other easy-to- review contributions. +* For PRs, add contributors to the GitHub repository that they contributed to using the [All Contributors bot](https://allcontributors.org/) using the command: `@all-contributors add @githubusername for code, review` (if the contribution is a pull request) or `@all-contributors add @githubusername for review` (if the contribution is an issue +* **IMPORTANT:** Merge each all-contributor-bot PR's individually and immediately after they have been opened to avoid merge conflicts -**After a Sprint** +**After a sprint** +* Triage issues and pull requests +* Make sure all contributors have been added to each repo they've contributed to using the all-contributors bot. +* Focus on replying, addressing and merging pull requests as we can. If an issue has a lingering TODO - consider tagging it with a `help-wanted` label for a future sprint. +* Send followup *thank you for participating* notes +* Collect / process / aggregate sprint metrics ::: @@ -50,7 +55,7 @@ beneficial when we write grants and solicit sponsorships. pyOpenSci uses a combination of GitHub project boards and user surveys to track participation and success metrics. More on that below. -## Sprint Participant Motivations +## What motivates sprint participants? Sprint participants are often motivated by different things. Some come to: @@ -58,9 +63,11 @@ Sprint participants are often motivated by different things. Some come to: * help and support a project they care about * connect and build community -pyOpenSci supports and empowers all of these motivations, with an emphasis on -empowering contributors who are newer to contributing, while greatly benefiting -from more experienced sprinters who can help move the organization forward. +pyOpenSci supports and empowers all of the above motivations. We thrive on empowering new +empowering contributors to make their first (or second) contributions! This impact aligns well with our mission. We also greatly benefit +from more experienced sprinters who can help move the organization's infrastructure and needs forward. + +Sprints are always a win/win for pyOpenSci. ### pyOpenSci sprints are accessible @@ -68,26 +75,35 @@ It's important to pyOpenSci's mission that sprints are accessible to both new and seasoned contributors. We aim to ensure that all participants have a successful experience with our community. Some participants are new and are submitting their first-ever issue and/or pull request to an open source project. -These participants may need help using git and GitHub, or they may feel -intimidated by their first contribution. Others are more experienced and +These participants: + +* may need help using git and GitHub, or +* they may feel intimidated by their first contribution (but they want to try!). + +Others are more experienced and comfortable in a sprint environment but may have questions about more technical -open issues and the outcomes that pyOpenSci wants to see for issue solutions. +open issues and the outcomes that pyOpenSci wants to see in issue solutions. Supporting all of these participants is crucial to our mission and can require significant effort during a sprint event. -As such, it's important for anyone leading a sprint to come prepared! In some cases having community helpers will go along way to supporting beginner contributor success. - +As such, it's important for anyone leading a sprint to come prepared! In most cases having community helpers will go along way to supporting beginner contributor success. -## Sprint Infrastructure - GitHub Project Boards +## Sprint infrastructure - GitHub projects To efficiently manage and track contributions during sprints, pyOpenSci utilizes -GitHub project boards. These boards help us organize tasks that participants can work on. This ensures that +[GitHub projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). We use projects to organize issues and pull requests that contributors could potentially address during or outside of a sprint. Tasks that are discrete enough to complete during a sprint are labeled with the `sprintable` label. + +An organized project ensures that contributors, whether new or experienced, can easily find and work on tasks -that suit their skills and interests. They also are used to track new contributions that we get during an event. +that suit their skills and interests. -#### Help-Wanted Board +:::{not} +We also are testing out using [event projects](https://github.com/orgs/pyOpenSci/projects/12) to to track new contributions in the form of pull requests and issues that we receive during an event such as a PyCon US or SciPy sprint. +::: + +#### Help-wanted board -The pyOpenSci [**Help-Wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is an organization-level GitHub project board that provides a central place where contributors can +The pyOpenSci [**help-wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is an organization-level GitHub project board that provides a central place where contributors can find tasks that pyOpenSci needs help with. We have two automated workflows setup for the help-wanted project board: @@ -95,12 +111,12 @@ for the help-wanted project board: * When an issue or pull request is closed, it is automatically archived from the project board. Tasks on this board are ideally smaller, well-defined, and can be completed or significantly advanced within the -duration of a sprint. The pyOpenSci Help-Wanted board should be updated throughout the year as new issues are opened in our organization GitHub repositories. Continual updates makes it easier for: +duration of a sprint. The pyOpenSci help-wanted board should be updated throughout the year as new issues are opened in our organization GitHub repositories. Continual updates makes it easier for: * Contributors to jump in and start contributing and * Sprint leaders to prepare for a sprint as the board will be more up to date. -#### Annual Sprint Project Board +#### Tracking annual contributions: the sprint project board At the start of each year, the pyOpenSci community manager creates a new Sprint GitHub Project Board. Here is an example of the [2024 sprint project board](https://github.com/orgs/pyOpenSci/projects/12). @@ -114,12 +130,12 @@ The board will have several columns or statuses, each of which represents the na By using these boards, pyOpenSci staff can easily keep tabs of sprint activities and outcomes. It also helps us ensure that all sprint issues and pull requests are addressed in a timely manner. -### Year Round Sprint tasks +### Year round sprint tasks Below are tasks to stay on top of throughout the year. By working on these items as they pop up, you are saving time spent in preparing for a sprint. -#### Maintain the the pyOpenSci help-wanted project board +#### Maintain the pyOpenSci help-wanted project board pyOpenSci uses the GitHub [help-wanted project board](https://github.com/orgs/pyOpenSci/projects/3) to keep track of tasks that volunteers can assist with. When you see an issue @@ -168,11 +184,11 @@ If you are creating a new `help-wanted` issue, it's important to include as much When in doubt, more information is always better! ::: -Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. +It is important to label issues with `help-wanted` / `sprintable` throughout the year and as they are opened as we can. This will save significant when preparing for a sprint. It will also make it easier for fly-by contributors to find things to help us with throughout the year. -## Pre-Sprint Event Tasks +## Pre-sprint tasks -### Triage (Help-Wanted) Issues Across the pyOpenSci Organization +### Triage (help-wanted) issues across the pyOpenSci organization Before a sprint begins, someone on the pyOpenSci team should go through and triage all of the open issues in the organization to determine: @@ -200,18 +216,22 @@ One challenge of a successful sprint is that there will be many issues and pull The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a GitHub action on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. :::{todo} -test this workflow: https://github.com/actions/add-to-project in a single repo -NOTE - i'm not sure this will work. i forgot that pr templates are not as straight forward as issue templates are. issue templates are easier. +NOTE: i have setup this workflow https://github.com/actions/add-to-project on most (but not all) of our repos now. so it does handle moving help-wanted issues to the project. BUT it is hard to think about events. This is because there is no easy to use pull request template. so while we could automagically update a workflow before an event we'd have to do it for every event AND it would only work on issues - not pull requests. As such my idea of automating event tags won't work. + +For now - we should do that manually during the event. It would be an easy enough thing for jesse to do remotely i think? or i could do it IF the sprint slows down. it really didn't at pycon this year (2024) ::: + + +:::{todo} + +Jesse will flesh this out when it's ready! + ### Create a participant signup form * create the form * create a dynamic qr code that we can update (the is placed on our table top cards ) OR get a card that we can add a sticker to with the code and replace the stickers... - -:::{todo} - jesse will develop this process with whatever platform we end up using... ::: @@ -222,6 +242,8 @@ Below are tasks that should occur during a sprint event. ### Collect participant information +*This section will be fleshed out soon...* +:::{todo} The person running the event should collect information from participants at the event via ______ **TODO insert how we do that here** _____ following the process Jesse creates above.... @@ -229,13 +251,14 @@ at the event via ______ **TODO insert how we do that here** _____ following the * what do we collect? * how do they opt out of future coms? - -Metrics – +What Metrics do we collect and how? Number of PRs Number of issues Who contributed Where are the contributors from (country, place of work, other things??) +::: + ### Update the sprint issue and pull request board During the event, the remote sprint support team (either Community Manager or a volunteer), should: @@ -247,7 +270,7 @@ During the event, the remote sprint support team (either Community Manager or a This process, if done during the sprint, will make triaging issues and pull requests after the event, easier. :::{todo} -We create one issue and pr template that we can use across all our repos – it has a label that automatically will be added to the board with “no status” +We create one issue and pull requesttemplate that we can use across all our repos – it has a label that automatically will be added to the board with “no status” Jesse adds a label for the event and moves it to a column ::: @@ -273,7 +296,7 @@ To add contributors to the repository using the All-Contributors bot: `@all-contributors add @githubusername for ` -If they have opened an issue only, or reviewed an open pr use: +If they have opened an issue only, or reviewed an open pull request use: `@all-contributors add @githubusername for review` @@ -287,7 +310,7 @@ contributors list when you call the commands above. IMPORTANT: Merge each all-Co By recognizing contributors for their efforts, we foster a positive and inclusive community, encouraging more participation and collaboration. -## After a Sprint tasks +## After a sprint tasks ### Issue and PR triage The biggest effort after a sprint will be triaging & addressing issues and pull requests that have been submitted during the sprint. This could take 1-2 weeks and up to a month depending on the scope of each change submitted. diff --git a/conf.py b/conf.py index d7ec7e0..65fbd6b 100644 --- a/conf.py +++ b/conf.py @@ -29,7 +29,9 @@ # Get the latest Git tag - there might be a prettier way to do this but... try: release_value = ( - subprocess.check_output(["git", "describe", "--tags"]).decode("utf-8").strip() + subprocess.check_output(["git", "describe", "--tags"]) + .decode("utf-8") + .strip() ) release_value = release_value[:4] except subprocess.CalledProcessError: From fc73ece0a7d234ddf4f506c0446e36be026957f1 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 15:53:19 -0600 Subject: [PATCH 15/52] Final edits --- community/events/sprints.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index b0a348c..c791bea 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -341,7 +341,9 @@ steps to take: and community highlights. - **GitHub**: Remind them to continue following and contributing to pyOpenSci [repositories on GitHub](https://github.com/pyopensci). +:::{todo} - Discourse? +::: 4. **Stay Connected**: - **Upcoming Events**: Inform participants about upcoming sprints, webinars, @@ -350,26 +352,29 @@ steps to take: By thanking contributors you are helping to maintain the momentum generated during the sprint, while also fostering a sense of community, and encourage ongoing contributions to pyOpenSci projects. +### Final wrap up activities +We will have several outcome tasks to do to wrap up a sprint. These +are listed below: +* Blog post about the event with stats around activity (number of participants, pull requests, issues, etc). This post might highlight wins both big and "small"! +* Social media promoting the success of the event and above metrics +* LinkedIn newsletter reusing that blog post content +### Welcome new contributors to slack -Help for sprint event triage after the event -Event outputs -Blog post(s) -Social -Welcome new ppl to slack -Community Content “owners” -Related to above - help post event. We have a lot of issues and pr’s now. Can the community help with triage? - - +Because some participants come to sprints to learn, they may not stage engaged with pyOpenSci after a sprint event. As such it's best to invite +people who continue to stay engaged with us either via GitHub or some +other mechanism (becoming a reviewer, editor, submitting a package, etc). :::{admonition} Meeting metrics that pyOpenSci collects :class: info * Number of pull request submitted * Number of issues submitted * Number of contributors contributed - * Where are the contributors from (country, place of work, other things??) + * Where are the contributors from (country, place of work / organization) + * Type of user - student, professional, non profit/ public sector. + * Optional - demographics ::: From 34fcc11e77d03e9377db5eeebf7bf36f0e1b11ec Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 15:57:13 -0600 Subject: [PATCH 16/52] Fix: pre-commit --- community/events/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/community/events/intro.md b/community/events/intro.md index afca5ee..a2decfc 100644 --- a/community/events/intro.md +++ b/community/events/intro.md @@ -45,7 +45,7 @@ Prior to an in-person sprint, the following items should be created: :::{todo} will this work for events as we will want an event name associated with it but it would be annoying to make a new card for every event? UNLESS we make a bunch at once for all events for the year? -We are currently pricing out a travel banner, to be used outside a space where pyOpenSci is running a workshop. +We are currently pricing out a travel banner, to be used outside a space where pyOpenSci is running a workshop. An example of the [base/holder for the table top card](https://www.officedepot.com/a/products/5760240/American-Metalcraft-Stainless-Steel-Harp-Style/). We'll initially test out metal, as they will be less likely to break in transit, however acrylic options are also available. Cards will be designed and printed, all of which will contain, at minimum, the pyOpenSci logo, website address, and a QR code that links to all of our socials/mailing list. this way it'll give people a visual cue as to where pyOS is congregating, as well as the option to interact with us directly. From 2b9d5dd750fe44ab1b27e4b5c26dc69fe02528e0 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 17:08:05 -0600 Subject: [PATCH 17/52] Add links to tldr --- community/events/sprints.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index c791bea..65ee113 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -8,14 +8,14 @@ **Before a sprint** -* pyOpenSci staff go through the pyOpenSci repo issues and ensure all relevant **help-wanted** and/or **sprintable** both have appropriated labels and have been added to the the project board in the appropriate column (beginner-friendly, python, dev-ops/ci, Python, Sphinx). +* pyOpenSci staff go through the pyOpenSci repo issues and ensure all relevant **help-wanted** and/or **sprintable** both have appropriated labels and have been added to the the [GitHub project](github-project) in the appropriate column (beginner-friendly, python, dev-ops/ci, Python, Sphinx). * pyOpenSci staff ensure all issues on the project board have enough **specific** information for a new user to follow and complete the task needed to be done. The more specific the issue is, the fewer questions a sprinter / contributor will ask during a sprint. This saves significant time and energy for both the sprint attendee and whomever is leading the sprint. **During a sprint** * Label all newly submitted issues as `sprint-event`, `sprint-name-year` (example: `sprint`, `pyconus-24`) * Merge small PRs that are clearly mergeable without significant review. Examples might include: typo fixes and other easy-to- review contributions. -* For PRs, add contributors to the GitHub repository that they contributed to using the [All Contributors bot](https://allcontributors.org/) using the command: `@all-contributors add @githubusername for code, review` (if the contribution is a pull request) or `@all-contributors add @githubusername for review` (if the contribution is an issue +* For PRs, add contributors to the GitHub repository that they contributed to using the [All Contributors bot](https://allcontributors.org/) using the command: `@all-contributors add @githubusername for code, review` (if the contribution is a pull request) or `@all-contributors add @githubusername for review` (if the contribution is an issue). [More on using the bot here.](all-contribs) * **IMPORTANT:** Merge each all-contributor-bot PR's individually and immediately after they have been opened to avoid merge conflicts **After a sprint** @@ -88,6 +88,7 @@ significant effort during a sprint event. As such, it's important for anyone leading a sprint to come prepared! In most cases having community helpers will go along way to supporting beginner contributor success. +(github-project)= ## Sprint infrastructure - GitHub projects To efficiently manage and track contributions during sprints, pyOpenSci utilizes @@ -283,6 +284,7 @@ you see an issue opened that makes sense to work on remotely with a participant, We will need to feel some of this out at scipy. ::: +(all-contribs)= ### Acknowledge sprint contributors - All-Contributors Bot pyOpenSci uses the [All-Contributors bot](https://allcontributors.org/docs/en/bot/usage) From 4e03f268f1415190376827ec5d921b88fed23307 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 21 Jun 2024 14:07:41 -0600 Subject: [PATCH 18/52] Update pull-requests.md --- community/github/pull-requests.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/community/github/pull-requests.md b/community/github/pull-requests.md index 5f5d727..3e7fdfd 100644 --- a/community/github/pull-requests.md +++ b/community/github/pull-requests.md @@ -4,7 +4,14 @@ When possible, pull request and issue submissions and reviews should follow stan ## Pull Requests -Authors of new pull requests should whenever possible, do their best to create clean pull requests. A clean pull request: +New pull requests should: + +* be created from a fork rather than the pyOpenSci owned parent repository. +* never be submitted from the `main` branch of your fork. + +Authors of new pull requests should whenever possible, do their best to create clean pull requests. + +A clean pull request: * is focused, and easy to review, * can be more quickly reviewed (and in turn merged) so it saves everyone time. @@ -14,6 +21,10 @@ Authors of new pull requests should whenever possible, do their best to create c Review your own pull request before asking someone else to review it for you. You might be surprised that you notice things in the pull request that you didn't notice when working on the content locally. ::: +### Pull request content + +Below are some guidelines for pull request content. Clean pull requests lead to simpler reviews & faster merging! + 1. **Keep It Small**: Aim for one logical change per pull request to simplify review. 1. **Create descriptive PR Title and Summary**: Clearly state what the PR achieves and why, including any related issue numbers or discussions. 1. **Double check that the files committed to the pull request clearly align with the suggested changes being made in the pull request**. For example if a new guidebook page contains images, all images that are new to the guidebook should be included in the list of files in the pr. If the new page reuses images, then link to the existing images in the repository rather than re-adding them. @@ -29,6 +40,7 @@ Review your own pull request before asking someone else to review it for you. Yo :::{info} * [tips for better pull requests](https://opensource.com/article/18/6/anatomy-perfect-pull-request) +* pyOpenSci has also enabled a "update branch" feature in the pull request which will update your branch to be in sync with main. It creates a merge commit rather than a rebase in most cases. ::: ### Regular vs New Contributors From 5fef316f398dff1062551ebc3e1e1776edfd6b18 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Mon, 12 Aug 2024 16:16:44 -0600 Subject: [PATCH 19/52] add: readme for exec council notes --- reference/meeting-notes/executive-council/README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 reference/meeting-notes/executive-council/README.md diff --git a/reference/meeting-notes/executive-council/README.md b/reference/meeting-notes/executive-council/README.md new file mode 100644 index 0000000..d2d320b --- /dev/null +++ b/reference/meeting-notes/executive-council/README.md @@ -0,0 +1 @@ +## Executive council meeting notes From 03a97a9d7bdd0384cc7057cbc083f036009162ff Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 17:05:47 -0600 Subject: [PATCH 20/52] Add: page on github issues in our org --- community/github/issues.md | 82 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 community/github/issues.md diff --git a/community/github/issues.md b/community/github/issues.md new file mode 100644 index 0000000..cd31d12 --- /dev/null +++ b/community/github/issues.md @@ -0,0 +1,82 @@ +# pyOpenSci GitHub issue process + +When possible, pull request and issue submissions and reviews should follow +standard open source workflows. Below are guidelines for handling issues. + +## Guidelines for New Issues + + +**Issues in should be as specific as possible:** specifics within an issue help both our future selves and also outside contributors understand the goal or +desired outcome associated with addressing the issue. This is important both internally and for issues that we tag as `help-wanted`, which we hope community members will address in pyOpenSci sprints. + +To ensure an issue is well-written and specific, include the following details: + +- **Clear Title:** A concise and descriptive title summarizing the issue or feature request helps us scan through issues and understand what each issue is about. Below are some example titles that are specific + + * `Bug: broken link in link-to-page-here / name of page / document etc` + * `Fix: confusing paragraph on Python packaging with Hatch` + * `Add: page on using pixi for dependencies` + +- **Description:** A detailed explanation of the issue or feature request, including context, background information, and the reason for the request. Explain why the issue is important and what problem it solves. + +- **Screenshots/Code Samples:** Screenshots, code snippets, links, or any other relevant files that can help in understanding the issue better. + +- **Possible Solutions/Recommendations:** Any ideas or suggestions for how to address the issue, which can help guide contributors towards a solution. + +- **Related Issues or Pull Requests:** References to any related issues or pull requests, providing additional context and understanding of the broader scope of the issue. + +### If you are reporting a code bug + +* **Steps to Reproduce (for bugs):** A step-by-step guide on how to reproduce the issue, including relevant code snippets, commands, or configurations. + +* **Expected vs. Actual Behavior (for bugs):** A description of what you expected to happen and what actually happened. This helps in understanding the discrepancy and the impact of the bug. + +* **Environment Details (for bugs):** Details about the environment where the issue was observed, such as operating system, Python version, library versions, and any other relevant software/hardware details. + +### If you have permissions, label the issue + +While outside contributors will not have permission to label issues, pyOpenSci core team members and volunteers will. Be sure to add appropriate labels to +issues to make it easier to triage them. + +## Help-wanted / sprintable issues + +If an issue is something that anyone in the community could potentially +address, it's ideal to label the issue with `help-wanted` and/or `sprintable`. +A sprintable issue refers to an issue that could be completed or worked on +during a 1-2 day sprint, thus it should be smaller and more confined in scope. +A help-wanted issue is one that anyone is welcome to work on during whatever +time they have available. + +Once the `help-wanted` or `sprintable` issue label is added, the issue will be +automatically added to our +[pyOpenSci help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). +This automation is implemented currently for a single repository (the packaging guide) but we plan to implement it for other repositories using the add-to-project GitHub action. + + +:::{note} +The issue will be archived from the project board once it is closed. +::: + + +:::{todo} +Add link to sprints page when it's online +::: + +If an issue is unclear, a pyOpenSci staff member or designated community +member can ask the issue author to provide more information. + + + + + + +:::{todo} +Add section on labels +::: + +## Issue Maintenance + +Our goal at pyOpenSci is to keep our list of issues current and active. +Quarterly issue cleanup sessions should be implemented to ensure issues are +either being actively addressed or to assess whether older or stale issues can +be potentially closed. From e7951293076f39773cf13220217d63f88a22c61f Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 13 Aug 2024 13:21:15 -0600 Subject: [PATCH 21/52] Fix: edits from @kiersi Co-authored-by: Jesse Mostipak --- community/github/issues.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/community/github/issues.md b/community/github/issues.md index cd31d12..afa729b 100644 --- a/community/github/issues.md +++ b/community/github/issues.md @@ -1,12 +1,12 @@ # pyOpenSci GitHub issue process -When possible, pull request and issue submissions and reviews should follow +When possible, pull requests, issue submissions and reviews should follow standard open source workflows. Below are guidelines for handling issues. ## Guidelines for New Issues -**Issues in should be as specific as possible:** specifics within an issue help both our future selves and also outside contributors understand the goal or +**Issues should be as specific as possible:** specifics within an issue help both our future selves and also outside contributors understand the goal or desired outcome associated with addressing the issue. This is important both internally and for issues that we tag as `help-wanted`, which we hope community members will address in pyOpenSci sprints. To ensure an issue is well-written and specific, include the following details: @@ -19,15 +19,15 @@ To ensure an issue is well-written and specific, include the following details: - **Description:** A detailed explanation of the issue or feature request, including context, background information, and the reason for the request. Explain why the issue is important and what problem it solves. -- **Screenshots/Code Samples:** Screenshots, code snippets, links, or any other relevant files that can help in understanding the issue better. +- **Screenshots/Code Samples:** Include screenshots, code snippets, links, or any other relevant files that can help others in understanding the issue better. -- **Possible Solutions/Recommendations:** Any ideas or suggestions for how to address the issue, which can help guide contributors towards a solution. +- **Possible Solutions/Recommendations:** It's helpful to provide any ideas or suggestions for how to address the issue, which can help guide contributors towards a solution. -- **Related Issues or Pull Requests:** References to any related issues or pull requests, providing additional context and understanding of the broader scope of the issue. +- **Related Issues or Pull Requests:** Add references to any related issues or pull requests, which provides additional context and understanding of the broader scope of the issue. ### If you are reporting a code bug -* **Steps to Reproduce (for bugs):** A step-by-step guide on how to reproduce the issue, including relevant code snippets, commands, or configurations. +* **Steps to Reproduce (for bugs):** A step-by-step guide (generally a list or narrative) on how to reproduce the issue, including relevant code snippets, commands, or configurations. * **Expected vs. Actual Behavior (for bugs):** A description of what you expected to happen and what actually happened. This helps in understanding the discrepancy and the impact of the bug. @@ -50,7 +50,7 @@ time they have available. Once the `help-wanted` or `sprintable` issue label is added, the issue will be automatically added to our [pyOpenSci help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). -This automation is implemented currently for a single repository (the packaging guide) but we plan to implement it for other repositories using the add-to-project GitHub action. +This automation is implemented currently for a single repository (the packaging guide), but we plan to implement it for other repositories using the add-to-project GitHub action. :::{note} @@ -77,6 +77,6 @@ Add section on labels ## Issue Maintenance Our goal at pyOpenSci is to keep our list of issues current and active. -Quarterly issue cleanup sessions should be implemented to ensure issues are -either being actively addressed or to assess whether older or stale issues can -be potentially closed. +Quarterly issue cleanup sessions are implemented to ensure issues are +either being actively addressed, or to assess whether older or stale issues can +potentially be closed. From dfc0e63e0040cf26c660feeb68c0c0f7908498bf Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 13 Aug 2024 13:38:12 -0600 Subject: [PATCH 22/52] fix: edits to gh issues page --- community/github/intro.md | 17 +------ community/github/issues.md | 97 ++++++++++++++++++++++---------------- community/index.md | 8 ++-- 3 files changed, 61 insertions(+), 61 deletions(-) diff --git a/community/github/intro.md b/community/github/intro.md index d9b0538..e43d7a5 100644 --- a/community/github/intro.md +++ b/community/github/intro.md @@ -1,12 +1,7 @@ # GitHub -:::{todo} -1. for extra contributors - A pyOpenSci community member will review your post / contribution. you don't need to request a review. -1. -::: - - -pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci processes and content including: +pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci +processes and content including: * website content * tools that track contributors and keep the website up to date @@ -14,11 +9,3 @@ pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci proc This section of the guidebook discusses our GitHub organization, and processes for adding and managing content and infrastructure across the organization. - - -:::{toctree} -:glob: -:maxdepth: 2 - -* -::: diff --git a/community/github/issues.md b/community/github/issues.md index afa729b..3853b4c 100644 --- a/community/github/issues.md +++ b/community/github/issues.md @@ -1,82 +1,97 @@ # pyOpenSci GitHub issue process -When possible, pull requests, issue submissions and reviews should follow -standard open source workflows. Below are guidelines for handling issues. +When possible, GitHub pull requests, issue submissions, and reviews should follow +standard open source workflows. Below are guidelines for handling issues in the +pyOpenSci GitHub organization. -## Guidelines for New Issues +## Guidelines for new issues - -**Issues should be as specific as possible:** specifics within an issue help both our future selves and also outside contributors understand the goal or -desired outcome associated with addressing the issue. This is important both internally and for issues that we tag as `help-wanted`, which we hope community members will address in pyOpenSci sprints. +**Issues should be as specific as possible:** Specificity within an issue helps +both our future selves and outside contributors understand the goal or desired +outcome associated with addressing the issue. This is important both internally +and for issues tagged as `help-wanted`, which we hope community members will +address in pyOpenSci sprints. To ensure an issue is well-written and specific, include the following details: -- **Clear Title:** A concise and descriptive title summarizing the issue or feature request helps us scan through issues and understand what each issue is about. Below are some example titles that are specific +- **Clear title:** A concise and descriptive title summarizing the issue or + feature request helps us scan through issues and understand what each issue is + about. Below are some example titles that are specific: - * `Bug: broken link in link-to-page-here / name of page / document etc` - * `Fix: confusing paragraph on Python packaging with Hatch` - * `Add: page on using pixi for dependencies` + - `Bug: broken link in link-to-page-here / name of page / document etc` + - `Fix: confusing paragraph on Python packaging with Hatch` + - `Add: page on using pixi for dependencies` -- **Description:** A detailed explanation of the issue or feature request, including context, background information, and the reason for the request. Explain why the issue is important and what problem it solves. +- **Description:** A detailed explanation of the issue or feature request, + including context, background information, and the reason for the request. + Explain why the issue is important and what problem it solves. -- **Screenshots/Code Samples:** Include screenshots, code snippets, links, or any other relevant files that can help others in understanding the issue better. +- **Screenshots/code samples:** Include screenshots, code snippets, links, or + any other relevant files that can help others in understanding the issue + better. -- **Possible Solutions/Recommendations:** It's helpful to provide any ideas or suggestions for how to address the issue, which can help guide contributors towards a solution. +- **Possible solutions/recommendations:** It's helpful to provide any ideas or + suggestions for how to address the issue, which can help guide contributors + towards a solution. -- **Related Issues or Pull Requests:** Add references to any related issues or pull requests, which provides additional context and understanding of the broader scope of the issue. +- **Related issues or pull requests:** Add references to any related issues or + pull requests, which provides additional context and understanding of the + broader scope of the issue. ### If you are reporting a code bug -* **Steps to Reproduce (for bugs):** A step-by-step guide (generally a list or narrative) on how to reproduce the issue, including relevant code snippets, commands, or configurations. +- **Steps to reproduce (for bugs):** A step-by-step guide (generally a list or + narrative) on how to reproduce the issue, including relevant code snippets, + commands, or configurations. -* **Expected vs. Actual Behavior (for bugs):** A description of what you expected to happen and what actually happened. This helps in understanding the discrepancy and the impact of the bug. +- **Expected vs. actual behavior (for bugs):** A description of what you + expected to happen and what actually happened. This helps in understanding + the discrepancy and the impact of the bug. -* **Environment Details (for bugs):** Details about the environment where the issue was observed, such as operating system, Python version, library versions, and any other relevant software/hardware details. +- **Environment details (for bugs):** Details about the environment where the + issue was observed, such as operating system, Python version, library + versions, and any other relevant software/hardware details. ### If you have permissions, label the issue -While outside contributors will not have permission to label issues, pyOpenSci core team members and volunteers will. Be sure to add appropriate labels to -issues to make it easier to triage them. +While outside contributors will not have permission to label issues, pyOpenSci +core team members and volunteers will. Be sure to add appropriate labels to +issues to make them easier to triage. ## Help-wanted / sprintable issues -If an issue is something that anyone in the community could potentially -address, it's ideal to label the issue with `help-wanted` and/or `sprintable`. -A sprintable issue refers to an issue that could be completed or worked on -during a 1-2 day sprint, thus it should be smaller and more confined in scope. -A help-wanted issue is one that anyone is welcome to work on during whatever -time they have available. +If an issue is something that anyone in the community could potentially address, +it's ideal to label the issue with `help-wanted` and/or `sprintable`. A +sprintable issue refers to an issue that could be completed or worked on during +a 1-2 day sprint, thus it should be smaller and more confined in scope. A +help-wanted issue is one that anyone is welcome to work on during whatever time +they have available. Once the `help-wanted` or `sprintable` issue label is added, the issue will be automatically added to our [pyOpenSci help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). -This automation is implemented currently for a single repository (the packaging guide), but we plan to implement it for other repositories using the add-to-project GitHub action. - +This automation is implemented currently for a single repository (the packaging +guide), but we plan to implement it for other repositories using the +add-to-project GitHub action. :::{note} The issue will be archived from the project board once it is closed. ::: - -:::{todo} -Add link to sprints page when it's online +:::{seealso} +[Learn more about pyOpenSci sprint events.](/community/events/sprints) ::: -If an issue is unclear, a pyOpenSci staff member or designated community -member can ask the issue author to provide more information. - - - - - +If an issue is unclear, a pyOpenSci staff member or designated community member +can ask the issue author to provide more information. :::{todo} -Add section on labels +Add section on labels once we have things synced up across repos. ::: -## Issue Maintenance +## Issue maintenance Our goal at pyOpenSci is to keep our list of issues current and active. -Quarterly issue cleanup sessions are implemented to ensure issues are -either being actively addressed, or to assess whether older or stale issues can +Quarterly issue cleanup sessions are implemented to ensure issues are either +being actively addressed or to assess whether older or stale issues can potentially be closed. diff --git a/community/index.md b/community/index.md index 7cd529d..bb092eb 100644 --- a/community/index.md +++ b/community/index.md @@ -1,6 +1,5 @@ # Organization Handbook - :::{toctree} :hidden: :caption: Social Media Section @@ -9,20 +8,19 @@ Social Media Slack ::: - :::{toctree} :hidden: -:caption: GitHub Section +:caption: GitHub Processes GitHub +Our Repos +GitHub Issue Guidelines ::: - :::{toctree} :hidden: :caption: pyOpenSci Events Events pyOpenSci Sprints - ::: From 18f31390d83c9046a9fb75fe024cc28a2ced9c9b Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 13 Aug 2024 14:05:40 -0600 Subject: [PATCH 23/52] Fix: edits from @kiersi Co-authored-by: Jesse Mostipak --- community/github/continuous-integration.md | 40 ++++++++++++---------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/community/github/continuous-integration.md b/community/github/continuous-integration.md index a6f2679..68a7e98 100644 --- a/community/github/continuous-integration.md +++ b/community/github/continuous-integration.md @@ -2,25 +2,25 @@ ## What is CI? -Continuous Integration (CI) refers to checks and tests that run on every change (or commit) to a GitHub repository. In the pyOpenSci organization, each commit -triggers at least one or more automated CI workflows. For the website and sphinx books this build will: +Continuous Integration (CI) refers to checks and tests that are triggered by events that occur on GitHub such as commit pushes, pull requests and even merges to a GitHub repository. In the pyOpenSci organization, each commit +triggers at least one or more automated CI workflows. For the [pyOpenSci website repository](https://www.pyopensci.org/) and our online books such as the [Python packaging guidebook that is written using Sphinx](https://github.com/pyopensci/python-package-guide), this build will: * build the live rendered version of the online content with any changes added in the current commit(s) or pull requests. -* check the text for spelling issues, check images for missing alt tags and more +* check the text for spelling issues, check images for missing alt tags and more. If the repository has code, it will check for code style. -Having a CI setup on each pyOpenSci github repository ensures that we detect issues such as bad links, or broken code, before it's merged into the main repository. +Having a CI setup on each pyOpenSci GitHub repository ensures that we detect issues such as bad links or broken code before they're merged into the main repository. ### What do the green and red checks mean? The green and red checks in the CI block indicate the status of these automated checks: -* **Green Checks**: These indicate that the code has passed the CI checks. This means the code meets the project's standards and is likely +* **Green Checks**: These indicate that the code has passed the CI checks. This means the code meets the project's standards and is likely free from errors or issues related to the specific checks that have passed. -* **Red X's**: These indicate that the code has failed the associated CI checks. This means there are issues that need to be addressed before the code can be merged. The issues could be related to code style, formatting, tests, or other criteria specified by the CI configuration. +* **Red X's**: These indicate that the code has failed the associated CI checks. This means there are issues that need to be addressed before the code can be merged. The issues could be related to code style, formatting, tests, or other criteria specified by the CI configuration. #### If a CI check is red: @@ -29,19 +29,21 @@ free from errors or issues related to the specific checks that have passed. 3. **Make the necessary changes** to fix the issue. 4. **Push the updated code** to the pull request to trigger the CI checks again. -If something isn't working as expected or you are having a hard time understanding why CI is failing (we've all been there!) please ping someone else in the organization for help. As a pyOpenSci community, we are always here to help each other. +If something isn't working as expected or you are having a hard time understanding why CI is failing (we've all been there!), please ping someone else in the organization for help. As a pyOpenSci community, we are always here to help each other. -If all CI checks are green, you are good to go. Ping someone to review your pull request. The pull request can be merged once you have a approval from another repository owner. +If all CI checks are green, you are good to go. Ping a pyOpenSci repository owner on GitHub to review your pull request. The pull request can be merged once you have approval from another repository owner. + +If you don't know who to ping, no worries. Someone from the pyOpenSci organization will see your pull request and get back to you. :::{note} -Generally we require a single passing approval in order to merge a pull request. however, in some cases, if you are a pyOpenSci staff member or community member with admin / write access, it could be the case that you need to merge something immediately (ie fixing a small piece of breaking code, a spelling error, or adding a new piece of content that has already been agreed upon). +Generally we require a single passing approval in order to merge a pull request. However, in some cases, if you are a pyOpenSci staff member or community member with admin / write access, it could be the case that you need to merge something immediately (i.e. fixing a small piece of breaking code, a spelling error, or adding a new piece of content that has already been agreed upon). ::: ## CI and outside contributors If someone from outside of the pyOpenSci organization submits a pull request, then someone within the organization needs to approve and run CI. If you -have those super powers, please go ahead and allow CI to run for new contributors. You can’t break anything by running CI so always feel confident in our repos clicking that button if the PR is legitimate and submitted from a valid user! +have those super powers, please go ahead and allow CI to run for new contributors. You can’t break anything by running CI, so always feel confident in our repos when you click that button, assuming that the PR is legitimate and submitted from a valid user! Next to each CI step that was run, there is a details button. If you click on that link, it will give you more information about what has run / not run as expected in the build. @@ -49,8 +51,8 @@ Next to each CI step that was run, there is a details button. If you click on th All of our website repositories have several CI builds including: 1. A link checker -2. htmlproofer that checks both links and alt tags, images -3. a CI build that shows you what the rendered site looks like when built online. Currently we are using CircleCI for that live rendered build as CircleCi allows for in browser website build checks. GitHub requires you to download, unzip and view and archive with the build site locally. +2. `htmlproofer`, which checks both links and alt tags, as well as images +3. a CI build that shows you what the rendered site looks like when built online. Currently we are using [CircleCI](https://circleci.com/) for a live rendered build, as CircleCI allows for in-browser website build checks. GitHub requires you to download, unzip and view and archive with the build site locally. (pre-commit-ci)= @@ -60,29 +62,29 @@ The [Pre-commit CI bot](https://pre-commit.ci/) is a continuous integration serv runs pre-commit hooks on each pull request. This helps maintain code quality and consistency without requiring developers to run pre-commit locally. -TO run the bot on a pr, add the command below to a comment: +To run the bot on a PR, add the following command to a standalone comment: `pre-commit autofix` -When you do this, the bot will run all of the hooks that it can in place adding +When you do this, the bot will run all of the hooks that it can, adding a new commit to the pull request for you. #### What the Bot Can Fix -The bot can fix many linting and style issues in our content in place including: +The bot can in-place fix many linting and style issues in our content, including: -* Automatically fix formatting issues such as trailing whitespace and missing +* Automatically fixing formatting issues such as trailing whitespace and missing newlines. -* Apply code style adjustments as specified by hooks like `black` and `isort`. +* Apply code style adjustments as specified by hooks like [`black`](https://github.com/psf/black) and [`isort`](https://pycqa.github.io/isort/). #### What the Bot Can’t Fix -The bot can't fix some things such as: +The bot can't fix some things, such as: * Logical errors or bugs in the code. * Issues that require human judgment, such as resolving complex merge conflicts or making design decisions. -* Spelling errors +* Spelling errors. In the case that the bot finds errors that it can't fix, you will need to make those changes locally. From 6518d27359d81e7a3e9f2b0c5d3b476f5fc8395f Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 13 Aug 2024 14:08:36 -0600 Subject: [PATCH 24/52] Fix: edits from @kiersi Co-authored-by: Jesse Mostipak --- community/github/pull-requests.md | 74 +++++++++++++++---------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/community/github/pull-requests.md b/community/github/pull-requests.md index 3e7fdfd..298e3de 100644 --- a/community/github/pull-requests.md +++ b/community/github/pull-requests.md @@ -9,13 +9,13 @@ New pull requests should: * be created from a fork rather than the pyOpenSci owned parent repository. * never be submitted from the `main` branch of your fork. -Authors of new pull requests should whenever possible, do their best to create clean pull requests. +Authors of new pull requests should, whenever possible, do their best to create clean pull requests. A clean pull request: * is focused, and easy to review, -* can be more quickly reviewed (and in turn merged) so it saves everyone time. -* closes an existing issue (with the exception of new content such as blog posts that we manage internally using Asana) +* can be more quickly reviewed (and in turn merged), saving everyone time, and +* closes an existing issue (with the exception of new content such as blog posts, which we manage internally using Asana) :::{tip} Review your own pull request before asking someone else to review it for you. You might be surprised that you notice things in the pull request that you didn't notice when working on the content locally. @@ -26,44 +26,44 @@ Review your own pull request before asking someone else to review it for you. Yo Below are some guidelines for pull request content. Clean pull requests lead to simpler reviews & faster merging! 1. **Keep It Small**: Aim for one logical change per pull request to simplify review. -1. **Create descriptive PR Title and Summary**: Clearly state what the PR achieves and why, including any related issue numbers or discussions. -1. **Double check that the files committed to the pull request clearly align with the suggested changes being made in the pull request**. For example if a new guidebook page contains images, all images that are new to the guidebook should be included in the list of files in the pr. If the new page reuses images, then link to the existing images in the repository rather than re-adding them. -1. **Follow Coding / style guide and other organization Standards (if applicable)**: Stick to the project's coding guidelines for style and organization if they exist. This is more often relevant to code pull requests than text. -1. **Review Your Own Pull request first**: Look over your PR critically before requesting reviews to catch any mistakes early. +1. **Create a descriptive PR Title and Summary**: Clearly state what the PR achieves and why, including any related issue numbers or discussions. +1. **Double check that the files committed to the pull request clearly align with the suggested changes being made in the pull request**. For example, if a new guidebook page contains images, all images that are new to the guidebook should be included in the list of files in the pr. If the new page reuses images, then link to the existing images in the repository rather than re-adding them. +1. **Follow coding / style guide and other organization standards (if applicable)**: Stick to the project's coding guidelines for style and organization, if they exist. This is more often relevant to code pull requests than text. +1. **Review Your Own Pull request first**: Look over your PR critically before requesting reviews, in order to catch any mistakes early. 1. **Respond Respectfully**: Be open to feedback and discuss suggestions to improve the project. -1. **Check CI for any red x's (more on CI below)**: If your pull request returns a red X in the "checks/CI" section, then it's worth seeing if you can figure out what is broken in the build. If you aren't sure - no problem. Leave a note for the reviewer to allow them to help you understand what needs to be fixed (if anything). +1. **Check CI for any red X's (more on CI below)**: If your pull request returns a red X in the "checks/CI" section, then it's worth seeing if you can figure out what is broken in the build. If you aren't sure, no problem. Leave a note for the reviewer to allow them to help you understand what needs to be fixed (if anything). ### Highly Recommended -1. **Create clear Commit Messages**: Explain why changes are made, not just what was changed. -1. **Keep Your Branch Updated**: Regularly rebase your fork from the main branch (is possible) to avoid / clean up any merge conflicts and to keep your PR up to date. +1. **Create clear commit messages**: Explain why changes are made, not just what was changed. +1. **Keep your branch updated**: Regularly rebase your fork from the main branch (if possible) to avoid / clean up any merge conflicts and to keep your PR up to date. :::{info} * [tips for better pull requests](https://opensource.com/article/18/6/anatomy-perfect-pull-request) -* pyOpenSci has also enabled a "update branch" feature in the pull request which will update your branch to be in sync with main. It creates a merge commit rather than a rebase in most cases. +* pyOpenSci has also enabled an "update branch" feature in the pull request, which will update your branch to be in sync with main. In most cases, this creates a merge commit rather than a rebase. ::: ### Regular vs New Contributors There is no right or wrong when it comes to building a website repository locally. pyOpenSci staff and other community members who contribute to pyOpenSci regularly will often opt to build online resources locally for live interactive development and edits. Building locally -is an ideal way for internal contributors to double check website updates before pushing to github and looking at GitHub action updates. +is an ideal way for internal contributors to double check website updates before pushing to GitHub and looking at GitHub action updates. Contributors making less-regular contributions, or those submitting quick fixes to pages on our website, might opt to use our continuous integration (CI) checks as a way to double check the website build and also to check for broken and bad links, missing alt tags and more within a pull request. -A large volume of the content in our GitHub repositories is text based -documentation and tutorials. For text based repositories such as our -website, packaging guide and peer review guide, we have CI platforms setup that allow a contributor to submit a pull request with a change, without needing to build the site locally. +A large volume of the content in our GitHub repositories is text-based +documentation and tutorials. For text-based repositories, such as our +website, packaging guide and peer review guide, we have CI platforms set up that allow a contributor to submit a pull request with a change, without needing to build the site locally. ### Supporting new contributors -pyOpenSci strives to support new and existing contributors in enhancing our online resources. As such we will support new contributors in this process. When a new pull request is submitted by someone we will do the following: +pyOpenSci strives to support new and existing contributors in enhancing our online resources. As such, we will support new contributors in this process. When a new pull request is submitted by someone, we will do the following: -* Evaluate the contributors background if that is possible. If this is their first pull request submitted through a sprint, then support them in their efforts by pointing out CI and provide specific line-by-line feedback. -* If fixes to the existing pr are straight forward, the reviewer can "suggest inline changes" on the pull request by highlighting 1 or more modified lines, and suggesting edits in place. This approach of inline suggestions, is often a quick way to integrate feedback from a review -* If fixes to the existing PR are more involved, clearly articulate what is wrong in the pull request, and ask the contributor if they feel comfortable addressing it. If they don't, then someone in the core pyOpenSci team can support them in getting their pull request edited, reviewed and merged. +* Evaluate the contributors background, where possible. If this is their first pull request submitted through a sprint, then we'll support them in their efforts by pointing out CI and providing specific line-by-line feedback. +* If fixes to the existing pr are straight forward, the reviewer can "suggest inline changes" on the pull request by highlighting one or more modified lines, and suggesting edits in place. This approach of inline suggestions is often a quick way to integrate feedback from a review. +* If fixes to the existing PR are more involved, clearly articulate what is wrong in the pull request and ask the contributor if they feel comfortable addressing it. If they don't, then someone in the core pyOpenSci team can support them in getting their pull request edited, reviewed and merged. -The above process is often implemented on a case by case basis depending on the contributors background. +The above process is often implemented on a case-by-case basis depending on the contributor's background. :::{todo} Did we address these questions above?? @@ -76,22 +76,22 @@ Do we expect someone to have done all the wrangling with Ruby and Jekyll? ## Pull requests and Continuous Integration -At the bottom of every pull request is the Continuous Integration (CI) block. This block contains a set of checks that pyOpenSci has setup. Each check will have a red X's or green check next to it. +At the bottom of every pull request is the Continuous Integration (CI) block. This block contains a set of checks that pyOpenSci has set up. Each check will have a red X or green check next to it. ## Pre-commit hooks and pre-commit.ci bot -pyOpenSci uses [pre-commit](https://pre-commit.com/) and the [precommit.ci bot](https://pre-commit.ci/) to style check our repositories. This ensures our codebase remains clean, consistent, and free +pyOpenSci uses [pre-commit](https://pre-commit.com/) and the [precommit.ci bot](https://pre-commit.ci/) to style-check our repositories. This ensures our codebase remains clean, consistent, and free from common errors. -For all repositories we enable hooks that: +For all repositories, we enable hooks that: -* Look for extra spaces at the end of files -* Clean up trailing white space at the end of individual lines +* Look for extra spaces at the end of files. +* Clean up trailing white space at the end of individual lines. * Check for spelling issues within the repository. For code repositories, we have several additional checks including: -* Code format & style checks (e.g. black, isort) +* Code format & style checks (e.g. black, isort). ### About Pre-commit @@ -112,8 +112,8 @@ We generally use the following hooks: - `codespell` Setting up pre-commit locally is optional because we have the pre-commit bot -setup in our CI workflows. However, if you are a pyOpenSci staff member regularly contributors, we suggest that you set it up locally in our repos to ensure -spell check errors (that the pre-commit ci bot can not fix in a pr) are addressed. +setup in our CI workflows. However, if you are a pyOpenSci staff member regularly contributes, we suggest that you set it up locally in our repos to ensure +spell check errors (that the pre-commit CI bot cannot fix in a PR) are addressed. ### Setting Up Pre-commit Locally @@ -131,7 +131,7 @@ hooks on, run pre-commit install ``` This will install all of the hooks that pyOpenSci has setup for that repository. -Most often there is a spell checker, and several markdown file formatters that +Most often there is a spell checker, and several markdown file formatters, which will remove excess white space. @@ -144,7 +144,7 @@ will remove excess white space. 4. pre-commit will run on all files that you modify pre-commit will run after you add and commit a change to the repository locally. -Sometimes you may need to override pre-commit - for example if you have a +Sometimes you may need to override pre-commit—for example if you have a spelling issue that you know is correct, but pre-commit thinks is wrong, you may want to force commit that change and ask for help in the repo when you open a pr. @@ -165,16 +165,16 @@ to fix any issues with the pull request (with the exception of misspelled words) This helps maintain code quality and consistency without requiring contributors to run pre-commit locally. -[Learn more about pre-commit ci in our ci section here](pre-commit-ci) +[Learn more about pre-commit ci in our CI section here](pre-commit-ci) ### Acknowledging New Contributors We use the [All-contributors bot](https://allcontributors.org/) to acknowledge contributors across all of our GitHub repositories. Contributor information -is then published on [our website here](https://www.pyopensci.org/our-community/index.html#pyopensci-community-contributors). +is then published on [our website](https://www.pyopensci.org/our-community/index.html#pyopensci-community-contributors). ### Who we acknowledge -pyOpenSci is liberal in acknowledging all contributions large to small. When +pyOpenSci is liberal in acknowledging all contributions, regardless of their size. When someone new submits an issue or PR, add them as a contributor to the repo using the bot. @@ -182,12 +182,12 @@ the bot. if this is their first contribution to a different repo, or a different type of contribution, add them. We will acknowledge the different types of contributions that our wonderful volunteers make. * If they are already added as a contributor to the repo where the pull request is, that is ok too. The bot will inform you! -To add a contributor - at the bottom of a pull request or an issue - call the +To add a contributor, at the bottom of a pull request or an issue, call the following command: `@all-contributors please add @kiersi for code, review` -Replaceing `@kiersi` with `@contributors-username`. +replaceing `@kiersi` with `@contributors-username`. When you add a user, the bot will open a pull request that can be squashed and merged. Once merged, their profile image and name will appear in the @@ -202,10 +202,10 @@ the contributor list and noting the type(s) of contributions that they have made :::{todo} ## GitHub & CI -* Ci (Continuous integration) will be run on each new commit added to all of our public repositories (that have content). +* CI (Continuous integration) will be run on each new commit added to all of our public repositories (that have content). ### Permissions to run CI -In general, things are setup so CI doesn’t run automagically for new contributors. Rather, someone with triage (?) rights will need to approve the workflow to run by hitting the approve and run button that will appear (see image below). We have things setup this way to avoid spam pr’s commits that will abuse our CI use. We could potentially adjust in the future - but also we could adjust but allowing more people with “access levels” that can approve CI. +In general, things are setup so CI doesn’t run automagically for new contributors. Rather, someone with triage rights will need to approve the workflow to run by hitting the approve and run button that will appear (see image below). We have things set up this way to avoid spam PRs and commits that will abuse our CI use. We could potentially adjust in the future, but also can adjust by allowing more people with “access levels” that can approve CI. ::: From 9fba332d64dbaf18f0ee86c33adf635131fa84f1 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 16:55:20 -0600 Subject: [PATCH 25/52] Add: help wanted workflow to add issues to project --- .github/workflows/add-help-wanted.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .github/workflows/add-help-wanted.yml diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml new file mode 100644 index 0000000..430d713 --- /dev/null +++ b/.github/workflows/add-help-wanted.yml @@ -0,0 +1,22 @@ +name: Add help-wanted issues to help wanted board + +on: + issues: + types: + - labeled + +jobs: + add-help-wanted: + runs-on: ubuntu-latest + permissions: + repository-projects: write + steps: + - uses: actions/checkout@v4 + - name: Add issue to project + id: add-to-project + uses: actions/add-to-project@v1.0.1 + with: + project-url: https://github.com/orgs/pyOpenSci/projects/3 + github-token: ${{ secrets.GHPROJECT_TOKEN }} + labeled: help-wanted, sprintable + label-operator: OR From 3483d79d1075355b7cfb375aba09759c999cee8d Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 16:59:51 -0600 Subject: [PATCH 26/52] Update add-help-wanted.yml --- .github/workflows/add-help-wanted.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml index 430d713..9a11f66 100644 --- a/.github/workflows/add-help-wanted.yml +++ b/.github/workflows/add-help-wanted.yml @@ -8,10 +8,7 @@ on: jobs: add-help-wanted: runs-on: ubuntu-latest - permissions: - repository-projects: write steps: - - uses: actions/checkout@v4 - name: Add issue to project id: add-to-project uses: actions/add-to-project@v1.0.1 From cf7bb2070626c3250f3af36565d5f88d26527f4f Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 17:03:51 -0600 Subject: [PATCH 27/52] Fix: add conditional for label name --- .github/workflows/add-help-wanted.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml index 9a11f66..79bf714 100644 --- a/.github/workflows/add-help-wanted.yml +++ b/.github/workflows/add-help-wanted.yml @@ -10,6 +10,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Add issue to project + if: contains(github.event.label.name, 'help-wanted') || contains(github.event.label.name, 'sprintable') id: add-to-project uses: actions/add-to-project@v1.0.1 with: From ea879b2728364a6a50c4729780f504be14c6f028 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 17:07:49 -0600 Subject: [PATCH 28/52] Update add-help-wanted.yml --- .github/workflows/add-help-wanted.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml index 79bf714..39b412f 100644 --- a/.github/workflows/add-help-wanted.yml +++ b/.github/workflows/add-help-wanted.yml @@ -15,6 +15,7 @@ jobs: uses: actions/add-to-project@v1.0.1 with: project-url: https://github.com/orgs/pyOpenSci/projects/3 - github-token: ${{ secrets.GHPROJECT_TOKEN }} + # This is a organization level token so it can be used across all repos in our org + github-token: ${{ secrets.GHPROJECT_HELP_WANTED }} labeled: help-wanted, sprintable label-operator: OR From e71202a97034d2f851a74c58c113d933119b4100 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 17:11:07 -0600 Subject: [PATCH 29/52] Update add-help-wanted.yml --- .github/workflows/add-help-wanted.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml index 39b412f..771b028 100644 --- a/.github/workflows/add-help-wanted.yml +++ b/.github/workflows/add-help-wanted.yml @@ -10,7 +10,6 @@ jobs: runs-on: ubuntu-latest steps: - name: Add issue to project - if: contains(github.event.label.name, 'help-wanted') || contains(github.event.label.name, 'sprintable') id: add-to-project uses: actions/add-to-project@v1.0.1 with: From 23652ab1b022ae46f6ce29c1631719cf67203e59 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 17:13:31 -0600 Subject: [PATCH 30/52] Fix: label name --- .github/workflows/add-help-wanted.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/add-help-wanted.yml b/.github/workflows/add-help-wanted.yml index 771b028..aca8ff8 100644 --- a/.github/workflows/add-help-wanted.yml +++ b/.github/workflows/add-help-wanted.yml @@ -16,5 +16,5 @@ jobs: project-url: https://github.com/orgs/pyOpenSci/projects/3 # This is a organization level token so it can be used across all repos in our org github-token: ${{ secrets.GHPROJECT_HELP_WANTED }} - labeled: help-wanted, sprintable + labeled: help wanted, sprintable label-operator: OR From 3d3b573bfe6e3ebc071ecda7a3b472a6e8e7551f Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 15:48:36 -0600 Subject: [PATCH 31/52] Add: github repo overview to the handbook --- community/github/intro.md | 11 +++++ community/github/our-repositories.md | 72 ++++++++++++++++++++-------- 2 files changed, 64 insertions(+), 19 deletions(-) diff --git a/community/github/intro.md b/community/github/intro.md index 530c963..3c2fbe0 100644 --- a/community/github/intro.md +++ b/community/github/intro.md @@ -18,3 +18,14 @@ pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci proc * website content * tools that track contributors and keep the website up to date * peer review + +This section of the guidebook discusses our GitHub organization and processes +for adding and managing content and infrastructure across the organization. + + +:::{toctree} +:glob: +:maxdepth: 2 + +* +::: diff --git a/community/github/our-repositories.md b/community/github/our-repositories.md index e8cf804..b60744d 100644 --- a/community/github/our-repositories.md +++ b/community/github/our-repositories.md @@ -1,13 +1,11 @@ -# 1. Our Repositories +# pyOpenSci GitHub Repositories :::{todo} Add repositories from the pyOpenSci organization. ::: -## pyOpenSci GitHub Repository Overview - pyOpenSci manages multiple GitHub repositories to support various community -activities. Below is a description of each core repository. +activities. Below is a description of each repository. ### [Software-review Repository](https://www.pyopensci.org/software-peer-review/) @@ -22,33 +20,60 @@ any changes. This template's data are processed by a Python workflow, and even small modifications could disrupt the language processing. ::: +## Software-peer-review Guidebook Repository -### Software-peer-review Guidebook Repository - -This repository hosts our [software peer review guide](https://www.pyopensci.org/software-peer-review/), -which includes instructions and guidelines for authors, editors, the editor in -chief, and the peer review triage team. It also details our peer review policies, +This repository hosts our [software peer review guidebook](https://www.pyopensci.org/software-peer-review/), +which documents the processes and guidelines for authors, editors, the editor in +chief, and the peer review triage team as they manage our open peer review process. It also details our peer review policies, partnerships, and the templates used in the review process. -### Python-package-guide Repository +## Python-package-guide Repository The [python-package-guide repository](https://www.pyopensci.org/python-package-guide/) contains our community-developed guidelines and tutorials on Python packaging. -These resources are beginner-friendly and reflect best practices. +These resources are beginner-friendly and reflect Python packaging best practices. -### [pyosMeta Repository](https://github.com/pyOpenSci/pyosMeta) +## [pyosMeta Repository](https://github.com/pyOpenSci/pyosMeta) -The pyosMeta repo contains a Python package published on PyPI that tracks our +The pyosMeta repository contains a Python package published on PyPI that we use to track our package review and contributor data. This data is used in a GitHub action to update our website. -### [pyopensci.github.io Repository](https://github.com/pyOpenSci/pyopensci.github.io) +:::{todo} +Add more information about the contributor data workflow ... +::: + +## [pyopensci.github.io Repository](https://github.com/pyOpenSci/pyopensci.github.io) -Our website, [pyOpenSci](https://www.pyopensci.org/), is hosted on GitHub and -uses the Jekyll Minimal Mistakes theme. The python packages page, contributor page and peer review team page are all updated automagically using a -GitHub action workflow that is supported by the pyosMeta Python package. The workflow runs every other week but can be triggered manually as a **workflow +This repository contains code and content that builds and publishes our pyOpenSci website. The website, [pyOpenSci](https://www.pyopensci.org/), is hosted on GitHub and +uses the Jekyll Minimal Mistakes theme. The Python packages page, contributor page and peer review team page are all updated automagically using a +GitHub action workflow that is supported by the pyosMeta Python package discussed above. The workflow runs every other week but can be triggered manually as a **workflow dispatch**. +### Critical CI workflows in this repository + +The [contributor workflow action](https://github.com/pyOpenSci/pyopensci.github.io/blob/main/.github/workflows/update-contribs-reviews.yml) is a custom GitHub +action that is used to update the following website pages: + +* contributor page +* package listing page +* editorial, advisory council and executive council listing + +It runs as a cron job every other week but also can be run manually as a workflow +dispatch. If you need to update our package listing or contributor list on +the fly, please run this action. + +The action will: + +1. parse through all of our accepted pyOpenSci packages +2. collect package names, authors, reviewers and editors +3. collect metadata for the packages authors reviewers and editors using the GitHub (REST) API +4. Create 2 output YAML files discussed below. + +The yaml output files and then used to populate content on the website. + +### Metadata stored in this repository + 1. **Packages.yml**: Updates the [Python Packages page](https://www.pyopensci.org/python-packages.html) by parsing reviews from software-review repository issues. 2. **Contributors.yml**: Updates the [Our Community page](https://www.pyopensci.org/our-community/index.html) @@ -59,7 +84,16 @@ Update the website contributors guide with general CI and specific Jekyll information. ::: +## [pyOpenSci Sphinx Theme](https://github.com/pyOpenSci/pyos-sphinx-theme) + +**Platform:** Sphinx book template that builds on top of the pydata_sphinx_theme + +All of our pyOpenSci sphinx books (Handbook, packaging guide, software review guide ) have been customized to match our pyOpenSci branding. This repo contains the start of a sphinx theme that will incorporate all of our branding so we do not have to manually apply the branding and update the branding individually in each repo. Rather we can update branding in the theme and it will be applied across all of our repositories that use the theme. + +Creating a theme was inspired by Chris Holdgraf's 2i2c Sphinx theme. + ## [Handbook Repository](https://github.com/pyOpenSci/handbook) -The handbook repository hosts content that helps the community navigate our -online resources and communication channels. +**Platform:** Sphinx book running the pydata_sphinx_theme + +This is where we store our organization governance, code of conduct and processes around how we operate as an organization. From e278438db7538abcebb59c4a5a6723955f2de2d7 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 15:51:30 -0600 Subject: [PATCH 32/52] Fix: add pyosPackage repo to list --- community/github/our-repositories.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/community/github/our-repositories.md b/community/github/our-repositories.md index b60744d..9dbc5b9 100644 --- a/community/github/our-repositories.md +++ b/community/github/our-repositories.md @@ -97,3 +97,10 @@ Creating a theme was inspired by Chris Holdgraf's 2i2c Sphinx theme. **Platform:** Sphinx book running the pydata_sphinx_theme This is where we store our organization governance, code of conduct and processes around how we operate as an organization. + +## [pyosPackage repository](https://github.com/pyOpenSci/pyosPackage) + +The pyosPackage repo contains an example pure-Python package that compliments +our package guide & tutorials. We will build this package example out over time +for folks that just want to see a working package without creating one +themselves. From c5bb3b1e4c7740ff0928318861a2dfda1e9f28e5 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 16:57:22 -0600 Subject: [PATCH 33/52] Fix: edits from @kiersi Co-authored-by: Jesse Mostipak --- community/github/intro.md | 2 +- community/github/our-repositories.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/community/github/intro.md b/community/github/intro.md index 3c2fbe0..db69213 100644 --- a/community/github/intro.md +++ b/community/github/intro.md @@ -19,7 +19,7 @@ pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci proc * tools that track contributors and keep the website up to date * peer review -This section of the guidebook discusses our GitHub organization and processes +This section of the guidebook discusses our GitHub organization, and processes for adding and managing content and infrastructure across the organization. diff --git a/community/github/our-repositories.md b/community/github/our-repositories.md index 9dbc5b9..f11674b 100644 --- a/community/github/our-repositories.md +++ b/community/github/our-repositories.md @@ -23,8 +23,8 @@ small modifications could disrupt the language processing. ## Software-peer-review Guidebook Repository This repository hosts our [software peer review guidebook](https://www.pyopensci.org/software-peer-review/), -which documents the processes and guidelines for authors, editors, the editor in -chief, and the peer review triage team as they manage our open peer review process. It also details our peer review policies, +which documents the processes and guidelines for authors, editors, the Editor in +Chief, and the peer review triage team as they manage our open peer review process. It also details our peer review policies, partnerships, and the templates used in the review process. ## Python-package-guide Repository @@ -46,7 +46,7 @@ Add more information about the contributor data workflow ... ## [pyopensci.github.io Repository](https://github.com/pyOpenSci/pyopensci.github.io) This repository contains code and content that builds and publishes our pyOpenSci website. The website, [pyOpenSci](https://www.pyopensci.org/), is hosted on GitHub and -uses the Jekyll Minimal Mistakes theme. The Python packages page, contributor page and peer review team page are all updated automagically using a +uses the [Jekyll Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/) theme. The Python packages page, contributor page and peer review team page are all updated automagically using a GitHub action workflow that is supported by the pyosMeta Python package discussed above. The workflow runs every other week but can be triggered manually as a **workflow dispatch**. @@ -70,7 +70,7 @@ The action will: 3. collect metadata for the packages authors reviewers and editors using the GitHub (REST) API 4. Create 2 output YAML files discussed below. -The yaml output files and then used to populate content on the website. +The YAML output files and then used to populate content on the website. ### Metadata stored in this repository @@ -88,9 +88,9 @@ information. **Platform:** Sphinx book template that builds on top of the pydata_sphinx_theme -All of our pyOpenSci sphinx books (Handbook, packaging guide, software review guide ) have been customized to match our pyOpenSci branding. This repo contains the start of a sphinx theme that will incorporate all of our branding so we do not have to manually apply the branding and update the branding individually in each repo. Rather we can update branding in the theme and it will be applied across all of our repositories that use the theme. +All of our pyOpenSci Sphinx books (handbook, packaging guide, software review guide ) have been customized to match our pyOpenSci branding. This repo contains the start of a Sphinx theme that will incorporate all of our branding, so we do not have to manually apply the branding and update it individually in each repo. Instead, we can update branding in the theme and it will be applied across all of our repositories that use the theme. -Creating a theme was inspired by Chris Holdgraf's 2i2c Sphinx theme. +Creating a theme was inspired by [Chris Holdgraf's](https://chrisholdgraf.com/) 2i2c Sphinx theme. ## [Handbook Repository](https://github.com/pyOpenSci/handbook) @@ -100,7 +100,7 @@ This is where we store our organization governance, code of conduct and processe ## [pyosPackage repository](https://github.com/pyOpenSci/pyosPackage) -The pyosPackage repo contains an example pure-Python package that compliments +The pyosPackage repo contains an example pure-Python package that complements our package guide & tutorials. We will build this package example out over time for folks that just want to see a working package without creating one themselves. From 9102ef22512f50b65638b5d2363ccce28e928cc7 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Thu, 30 May 2024 17:15:10 -0600 Subject: [PATCH 34/52] Add: sprint process to handbook --- community/events/intro.md | 56 ++++++++ community/events/sprints.md | 264 ++++++++++++++++++++++++++++++++++++ community/index.md | 10 ++ 3 files changed, 330 insertions(+) create mode 100644 community/events/intro.md create mode 100644 community/events/sprints.md diff --git a/community/events/intro.md b/community/events/intro.md new file mode 100644 index 0000000..a6eb3ec --- /dev/null +++ b/community/events/intro.md @@ -0,0 +1,56 @@ +# Meetings & Events + +## pyOpenSci meetings + +pyOpensci staff regularly attend community meetings (e.g. SciPy meeting, PyCon US, etc). If the meeting is in person, some of the staff may be in person at the event while the community manager / others might be supporting the event remotely. + +In these instances asynchronous communication and sharing of documents in an organized way is critical. + +### Event documents +For every meeting, pyOpenSci staff should create a Google drive folder located in our pyos-shared drive where meeting documents are stored. These documents may include talk and workshop proposals, attendee signup lists, graphics use in social media and out reach posts and more content related to the event. + +Before an event, pyOpenSci staff will make sure this folder is shared and supporting documents are added to it. Often the folder will be created prior to the event to store talk, Bof (birds of a feather), townhall and workshop proposals. + +:::{admonition} Team checkin prior to an event +:class: note + +Staff should also have a short check-in prior to an event to ensure that all documents, and elements needed for the event are shared, in the right place, etc. + +Because the internet might be an issue sometimes at an event, whomever is leading the event should always bring a pen and paper. +::: + +## Event social media and graphics + +The community manager will manage online “coms” and social media during an event. However it will be important for whomever is attending the event in person to be in asynchronous communication via the pyOpenSci Slack about key activities, findings, new cool things, etc to be posting about, promoting and highlighting. + +In some cases an event might “pop up” last minute - such as an Open Space at pyCon. In this case, the person attending the event may want to modify and reuse graphics posted on social media to publicize the event. + +To support this case, we should also create an event folder in our online graphics platform, Canva (our online graphics platform). This event specific folder will be where we store all graphics used to promote an event both before during and after in one place. This will make it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event or change in plans, as needed. + +:::{admonition} Share the Canva folder with the pyopensci-canva-team +:class: important + +Be sure to share the Canva folder with the `pyOpensci-canva-team` on Canva to ensure that the entire team has edit access to the graphics and can make last minute changes as needed! +Please also be sure to name files using expressive words that make them easy to find / use / reuse. +::: + +**ADD IMAGE** + +Image showing a pycon-24 folders in canva for an event. You can share the entire folder with the team to ensure the team has access to all of the contents inside. + +### Preparation prior to an event + +Prior to a, in-person sprint, you should have the following things created: + +1. A template "sign up" form with data fields that we collect from participants. This allows us to track who attends and event and to followup with them after (if they wish to have communication with us after) +1. A tabletop “card” that says pyOpenSci. You will need 2-3 cards on hand for any event in case participants are spread across a few tables. This card will be important for events like sprints, workshops and open spaces where pyOpenSci has one or more tables in a large room. It will signal to contributors that we are there and help people quickly find us. + * The card should have a qr code that is dynamic (so we can update the url that it points to). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank message to each participant using a mail-merge system. + +:::{todo} +will this work for events as we will want an event name associated with it but it would be annoying to make a new card for every event? UNLESS we make a bunch at once for all events for the year? + +And maybe a banner for a door if I'm running a workshop? +the table top thing looks like this: https://www.officedepot.com/a/products/5760240/American-Metalcraft-Stainless-Steel-Harp-Style/ (this is better than acrylic because it won't break, but we could do plastic if you prefer). + +we'd then print out (and laminate?) some kind of card that has the pyOpenSci logo, website, and a QR code that links to all of our socials//mailing list. this way it'll give people a visual cue as to where pyOS is congregating, as well as the option to interact with us directly. +::: diff --git a/community/events/sprints.md b/community/events/sprints.md new file mode 100644 index 0000000..6e7e503 --- /dev/null +++ b/community/events/sprints.md @@ -0,0 +1,264 @@ +# pyOpenSci sprints + +* TODO: https://github.com/actions/add-to-project?tab=readme-ov-file i think we want to set this up for all repos so this works for scipy. + +## What is a sprint? +A sprint is an open session where contributors come together to contribute to an open source project. Contributors may range from beginners, who are new to sprints, GitHub, and git, to experienced developers. Below we review how pyOpenSci runs sprints. + +There are three types of pyOpenSci sprint events: + +1. **Community Sprint Events**: pyOpenSci hosts these at meetings it attends, such as PyCon US and the SciPy meeting. +2. **Online Sprint Events**: pyOpenSci may hold its own sprint events online to encourage global contributions. +3. **Community-Hosted Sprint Events**: Contributors and community members host pyOpenSci sprint events at meetings they attend. + +During pyOpenSci sprints, contributors need tasks that are “sprintable.” +Sprintable tasks are those that can be worked on and potentially completed (or +partially completed) in a single sitting, whether that time is a half-day or a full day. + +Sprints can span 1-4 days but are most often 1-2 days long. + +### Tracking sprint contributions +Sprints often result in numerous pull requests and issues being opened by contributors. It’s important for pyOpenSci to track information around: + +* who is attending, +* where they are from (country, state etc) and +* what contributions they make. + +This information will support pyOpenSci's community impact and support and be +beneficial when we write grants and solicit sponsorships. + +#### How we track sprint outcomes +pyOpenSci tracks issues and pull requests created through community events using project boards. More on project board use is below. We track participation metrics +using _____ TODO MORE HERE ____ + +#### pyOpenSci sprints are accessible + +It's important to pyOpenSci's mission that sprints are accessible to both new +and seasoned contributors. We aim to ensure that all participants have a +successful experience with our community. Some participants are new and are +submitting their first-ever issue and/or pull request to an open source project. +These participants may need help using git and GitHub, or they may feel +intimidated by their first contribution. Others are more experienced and +comfortable in a sprint environment but may have questions about more technical +open issues and the outcomes that pyOpenSci wants to see for issue solutions. +Supporting all of these participants is crucial to our mission and can require +significant effort during a sprint event. + +As such, it's important for anyone leading a sprint to come prepared! + +### Sprint Participant Motivations + +Sprint participants are often motivated by different things: + +* Some come to learn. +* Some come to help and support a project they care about. +* Some come to connect and build community. + +pyOpenSci supports and empowers all of these motivations, with an emphasis on +empowering contributors who are newer to contributing while greatly benefiting +from more experienced sprinters who can help move the organization forward. + + +### Sprint Infrastructure - GitHub Project Boards + +To efficiently manage and track contributions during sprints, pyOpenSci utilizes +GitHub project boards. These boards help us organize tasks that participants can work on. This ensures that +contributors, whether new or experienced, can easily find and work on tasks +that suit their skills and interests. They also are used to track new contributions that we get during an event. + +#### Help-Wanted Board + +The pyOpenSci **Help-Wanted project board** is a organization level GitHub project board that provides a central place where contributors can +find tasks that pyOpenSci needs help with. We have two automated workflows setup +for the help-wanted project board: + +* Any issue or pull request with the `help-wanted` label is automatically added to this board. +* When an issue or pull request is closed, it is automatically archived from the project board. + +Tasks on this board are ideally smaller, well-defined, and can be completed or significantly advanced within the +duration of a sprint. The pyOpenSci Help-Wanted board is continuously updated to reflect +the current needs of pyOpenSci projects, making it easier for contributors to +jump in and start contributing. + +#### Annual Sprint Project Board + +At the start of each year, the pyOpenSci community manager creates a new Sprint +GitHub Project Board. The board will have several columns or statuses each or wchih represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: + +* **Track issues and pull requests opened during a sprint event** +* **Organize and Monitor Tasks**: Keep track of the progress of tasks during the sprint, ensuring clarity on which issues are being worked on and by whom. +- **Manage the Triage Process**: Keep track of which pull requests have been addressed and merged and which ones still need attention. +- **Calculate metrics**: Provide counts of activity that has occurred during a sprint event. + +By using these boards, pyOpenSci ensures that sprints are organized, efficient, +and accessible to all participants. + +### Year Round Sprint tasks + +Below are tasks to stay on top of throughout the year. By working on +these items as they pop up, you are saving time spent in preparing for a sprint. + +#### Maintain the the pyOpenSci help-wanted project board + +pyOpenSci uses the GitHub [help-wanted project board](https://github.com/orgs/pyOpenSci/projects/3) +to keep track of tasks that volunteers can assist with. When you see an issue +opened or if you open an issue yourself in any of our GitHub repositories within +our [pyOpenSci GitHub organization](https://www.github.com/pyopensci), always +consider whether the issue is something that someone else could help us with. + +If the issue is something that someone else in the community could do: + +1. **Add a `help-wanted` Label**: Any issue or pull request with the `help-wanted` + label in our organization will be automatically added to our [pyOpenSci + help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). + +2. **Add a `sprintable` Label (if applicable)**: If the task could be completed + during a sprint (meaning it is something that could be completed within an + hour and up to a single day's worth of work), also add the label `sprintable` + to the issue. + +3. **Update the Status on the Project Board**: Once the issue has been added to + the project board (it normally takes our CI workflow 30 seconds to a minute), + update the status of the issue on the project board based on the type of skill + needed. + + +The current types of tasks in our board include: + + * Python packaging + * Beginner friendly / non technical + * Dev Ops / GitHub actions (Continuous Integration) + * Python programming + * Website - css or ruby + +:::{todo} +we should add content review and sphinx as a status options for people that review our guidebook, run through tutorials etc. +::: + +:::{important} +If you are creating a new `help-wanted` issue it's critical that you include as much detailed information in the issue as possible. Imagine someone else reading the issue (that is not you!). In reading the issue, does an outside contributor have: + +* clearly understand the problem? (be specific, provide examples, links etc) +* have enough information to solve the problem? +* know exactly where the problem is occurring (provide links if you can or code examples ) +* have enough information needed to solve the problem? + +When in doubt, more information is always better! +::: + +Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a Sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. + +### Pre-Sprint Event Tasks + +#### Triage (Help-Wanted) Issues Across the pyOpenSci Organization + +Before a sprint begins, someone on the pyOpenSci team should go through and +triage all of the open issues in the organization to determine: + +* Whether some of them are sprintable. +* Whether they have enough specific and detailed information for someone to work + on the issue without too much help during a sprint. + +This could be a small team exercise at a pre-meeting event held online for +pyOpenSci staff and sprint community members (if there are any contributors +participating). + +The information found in the body of an issue is critical to running an effective +sprint. If the issue has very specific information that gives a potential +contributor everything they need to know to begin working, they will have fewer +questions during the sprint. If you have a table of 10-20 people sprinting for +pyOpenSci, this means the person running the sprint will have less to do on-site! +Sprints are busy—please add as much specific information as you can to each issue! + +#### THIS LIKELY WON'T WORK Ensure issue and pull request templates are up to date + +A challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues and pr's, during an event, every pyOpenSci GitHub repository should have a sprint issue and pull request template. Adding this template only needs to be completed once, however +if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a template. + +The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a workflow on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. + +NOTE - i'm not sure this will work. i forgot that pr templates are not as straight forward as issue templates are. issue templates are easier. + +### Tasks during a sprint + +Below are tasks that should occur during a spring event. + +#### Collect participant information + +The person running the event should collect information from participants +at the event via ______ **TODO insert how we do that here** _____. + +* dynamic qr code... that people can scan. with small table top signs? +* what do we collect? +* how do they opt out of future coms? + + +Metrics – +Number of pr’s +Number of issues +Who contributed +Where are the contributors from (country, place of work, other things??) + +### Update the sprint issue and pull request board + +During the event, the remote sprint support team (either community manager or a volunteer) , should + +* label all issues and pull requests as `sprint-event` and with the label for the event - e.g. `pyconus-24` as they are opened. +* Once that the sprint-event label is applied to an issue or pr, they with automatically be added to the project sprint board. +* Finally, once on the sprint board, they can then move each issue and pull request to the event name status on the sprint board. + +This process, if done during the sprint, will make triaging issues and pull requests after the event, easier. + +:::{todo} +We create one issue and pr template that we can use across all our repos – it has a label that automatically will be added to the board with “no status” +Jesse adds a label for the event and moves it to a column +::: + +### Review and triage pull requests and issues + +If you see small pull requests coming in that are clearly fixing things in a guidebook, please review them and approve if that makes sense. If +you see an issue opened that makes sense to work on, feel free to comment on it. + + + +All-contributors bot +Tagging issues and pr’s with sprint / event name +Creating a project board for sprint events +Writing this all up (let’s test drive for scipy) +Help for sprint event triage after the event +Event outputs +Blog post(s) +Social +Welcome new ppl to slack +Community Content “owners” +Related to above - help post event. We have a lot of issues and pr’s now. Can the community help with triage? + +### After a sprint + +* Followup with participants +* Send out an email thanking people after +* invite them to stay in touch / follow newsletter / follow linkedin, + + +## Meeting Metrics that pyOpenSci collects + +* Number of pr’s +* Number of issues +* Who contributed + * Where are the contributors from (country, place of work, other things??) + +:::{todo} +SPRINTS: Collecting information during - sprints, etc - process so we can work together? +GDPR compliant database +Attendees - where do we keep this info? +Name +State / country +Company / org? (Affiliation) +Email address +GH username +Domain(s) of expertise +Survey data +Current role +Workshops attended +Social handles +::: diff --git a/community/index.md b/community/index.md index 4eaa0f2..7cd529d 100644 --- a/community/index.md +++ b/community/index.md @@ -16,3 +16,13 @@ Slack GitHub ::: + + +:::{toctree} +:hidden: +:caption: pyOpenSci Events + +Events +pyOpenSci Sprints + +::: From 4f50040ec4768ab7011e9cb49f2462ba763a0144 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 12:24:05 -0600 Subject: [PATCH 35/52] Fix: more edits --- community/events/sprints.md | 75 ++++++++++++++++++++++++++++++++----- 1 file changed, 65 insertions(+), 10 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index 6e7e503..f9b90c9 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -2,6 +2,17 @@ * TODO: https://github.com/actions/add-to-project?tab=readme-ov-file i think we want to set this up for all repos so this works for scipy. +:::{admonition} TLDR +* summary here?? + +During sprint + +* label all issues as sprint-event, sprint-name-year +* merge small pr's that are clearly typo fixies, easy to review things +* add contributors as contributors to the repo using the all contributors bot @all-contributors add @githubusername for code, review (for an issue use review for a pr use code, review ). Merge each all contributor pr individually and immediately to avoid merge conflicts +::: + + ## What is a sprint? A sprint is an open session where contributors come together to contribute to an open source project. Contributors may range from beginners, who are new to sprints, GitHub, and git, to experienced developers. Below we review how pyOpenSci runs sprints. @@ -219,12 +230,62 @@ Jesse adds a label for the event and moves it to a column If you see small pull requests coming in that are clearly fixing things in a guidebook, please review them and approve if that makes sense. If you see an issue opened that makes sense to work on, feel free to comment on it. +## Acknowledge spring contirbutors - All-Contributors Bot + +pyOpenSci uses the [All-Contributors bot](https://allcontributors.org/docs/en/bot/usage) +to recognize and celebrate the contributions of all our contributors. This bot +helps automate the process of adding contributors to the repository, making it +easier to maintain accurate records of everyone's efforts. + +To add contributors to the repository using the All-Contributors bot: + +1. **Use the Bot Command**: In a comment on an issue or pull request, use the following command to add a contributor as follows. + `@all-contributors add @githubusername for ` + + if they have opened an issue only, or reviewed an open pr use: + + `@all-contributors add @githubusername for review` + if they have opened a pull request use: + `@all-contributors add @githubusername for code, review` + + +2. **Merge PRs Individually**: The bot will create a pull request to update the +contributors list. Merge each All-Contributors PR individually and immediately +to avoid merge conflicts. + +By recognizing contributors for their efforts, we foster a positive and inclusive +community, encouraging more participation and collaboration. + +## After a Sprint is complete + +After a sprint, we will follow up with participants to show our appreciation +and encourage continued engagement with the pyOpenSci community. Here are the key +steps to take: + +1. **Send a Thank You Email**: Send an email to all sprint participants thanking them for their contributions. Express gratitude for their time and effort, highlighting any significant achievements or milestones reached during the sprint. + +2. **Provide Feedback**: Include any relevant feedback or outcomes from the sprint. This could involve sharing metrics, such as the number of issues closed, pull requests merged, or any specific contributions that stood out. + +3. **Invite Continued Engagement**: + - **Newsletter**: Encourage participants to subscribe to the pyOpenSci newsletter + to stay updated on future events, news, and opportunities. + - **LinkedIn**: Invite them to follow pyOpenSci on LinkedIn for professional updates + and community highlights. + - **GitHub**: Remind them to continue following and contributing to pyOpenSci + repositories on GitHub. + - Discourse? + +4. **Stay Connected**: + - **Upcoming Events**: Inform participants about upcoming sprints, webinars, + workshops, or any other events they might be interested in. + +By taking these steps, you help maintain the momentum generated during the sprint, +foster a sense of community, and encourage ongoing contributions to pyOpenSci projects. + + + -All-contributors bot -Tagging issues and pr’s with sprint / event name -Creating a project board for sprint events -Writing this all up (let’s test drive for scipy) Help for sprint event triage after the event Event outputs Blog post(s) @@ -233,12 +294,6 @@ Welcome new ppl to slack Community Content “owners” Related to above - help post event. We have a lot of issues and pr’s now. Can the community help with triage? -### After a sprint - -* Followup with participants -* Send out an email thanking people after -* invite them to stay in touch / follow newsletter / follow linkedin, - ## Meeting Metrics that pyOpenSci collects From 12a88a4b656c185fa15318cba8a5d6e3484a1a4b Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 13:00:56 -0600 Subject: [PATCH 36/52] Fix: finish up sprint overview page --- community/events/intro.md | 10 +- community/events/sprints.md | 178 +++++++++++++++++++++++------------- 2 files changed, 115 insertions(+), 73 deletions(-) diff --git a/community/events/intro.md b/community/events/intro.md index a6eb3ec..6dbd38b 100644 --- a/community/events/intro.md +++ b/community/events/intro.md @@ -25,7 +25,7 @@ The community manager will manage online “coms” and social media during an e In some cases an event might “pop up” last minute - such as an Open Space at pyCon. In this case, the person attending the event may want to modify and reuse graphics posted on social media to publicize the event. -To support this case, we should also create an event folder in our online graphics platform, Canva (our online graphics platform). This event specific folder will be where we store all graphics used to promote an event both before during and after in one place. This will make it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event or change in plans, as needed. +To support this case, we should also create an event folder in our online graphics platform, Canva. This event specific folder will be where we store all graphics used to promote an event both before during and after in one place. This will make it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event or change in plans, as needed. :::{admonition} Share the Canva folder with the pyopensci-canva-team :class: important @@ -34,17 +34,13 @@ Be sure to share the Canva folder with the `pyOpensci-canva-team` on Canva to en Please also be sure to name files using expressive words that make them easy to find / use / reuse. ::: -**ADD IMAGE** - -Image showing a pycon-24 folders in canva for an event. You can share the entire folder with the team to ensure the team has access to all of the contents inside. - ### Preparation prior to an event -Prior to a, in-person sprint, you should have the following things created: +Prior to an, in-person sprint, you should have the following things created: 1. A template "sign up" form with data fields that we collect from participants. This allows us to track who attends and event and to followup with them after (if they wish to have communication with us after) 1. A tabletop “card” that says pyOpenSci. You will need 2-3 cards on hand for any event in case participants are spread across a few tables. This card will be important for events like sprints, workshops and open spaces where pyOpenSci has one or more tables in a large room. It will signal to contributors that we are there and help people quickly find us. - * The card should have a qr code that is dynamic (so we can update the url that it points to). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank message to each participant using a mail-merge system. + * The card should have a qr code that is dynamic (so we can update the url that it points to and reuse the cards). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank message to each participant using a mail-merge system. :::{todo} will this work for events as we will want an event name associated with it but it would be annoying to make a new card for every event? UNLESS we make a bunch at once for all events for the year? diff --git a/community/events/sprints.md b/community/events/sprints.md index f9b90c9..33e351c 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -1,15 +1,23 @@ # pyOpenSci sprints +:::{todo} * TODO: https://github.com/actions/add-to-project?tab=readme-ov-file i think we want to set this up for all repos so this works for scipy. +::: -:::{admonition} TLDR -* summary here?? +:::{admonition} TL;DR -During sprint +**Before sprint** +* Go through the pyOPenSci repo issues and ensure all relevant help-wanted / sprintable issues have labels and are on the project board. +* Also ensure all issues on the project board have enough specific information for a new user to follow and complete the task needed to be done. -* label all issues as sprint-event, sprint-name-year +**During sprint** + +* label all newly submitted issues as sprint-event, sprint-name-year * merge small pr's that are clearly typo fixies, easy to review things * add contributors as contributors to the repo using the all contributors bot @all-contributors add @githubusername for code, review (for an issue use review for a pr use code, review ). Merge each all contributor pr individually and immediately to avoid merge conflicts + +**After Sprint** + ::: @@ -31,18 +39,28 @@ Sprints can span 1-4 days but are most often 1-2 days long. ### Tracking sprint contributions Sprints often result in numerous pull requests and issues being opened by contributors. It’s important for pyOpenSci to track information around: -* who is attending, -* where they are from (country, state etc) and -* what contributions they make. +* Who is attending, +* Where they are from (country, state etc) and +* What contributions they make. This information will support pyOpenSci's community impact and support and be beneficial when we write grants and solicit sponsorships. -#### How we track sprint outcomes -pyOpenSci tracks issues and pull requests created through community events using project boards. More on project board use is below. We track participation metrics -using _____ TODO MORE HERE ____ +pyOpenSci uses a combination of GitHub project boards and user surveys to track participation and success metrics. More on that below. + +## Sprint Participant Motivations + +Sprint participants are often motivated by different things: -#### pyOpenSci sprints are accessible +* Some come to learn. +* Some come to help and support a project they care about. +* Some come to connect and build community. + +pyOpenSci supports and empowers all of these motivations, with an emphasis on +empowering contributors who are newer to contributing while greatly benefiting +from more experienced sprinters who can help move the organization forward. + +### pyOpenSci sprints are accessible It's important to pyOpenSci's mission that sprints are accessible to both new and seasoned contributors. We aim to ensure that all participants have a @@ -55,22 +73,10 @@ open issues and the outcomes that pyOpenSci wants to see for issue solutions. Supporting all of these participants is crucial to our mission and can require significant effort during a sprint event. -As such, it's important for anyone leading a sprint to come prepared! - -### Sprint Participant Motivations - -Sprint participants are often motivated by different things: - -* Some come to learn. -* Some come to help and support a project they care about. -* Some come to connect and build community. - -pyOpenSci supports and empowers all of these motivations, with an emphasis on -empowering contributors who are newer to contributing while greatly benefiting -from more experienced sprinters who can help move the organization forward. +As such, it's important for anyone leading a sprint to come prepared! In some cases having community helpers will go along way to supporting beginner contributor success. -### Sprint Infrastructure - GitHub Project Boards +## Sprint Infrastructure - GitHub Project Boards To efficiently manage and track contributions during sprints, pyOpenSci utilizes GitHub project boards. These boards help us organize tasks that participants can work on. This ensures that @@ -79,7 +85,7 @@ that suit their skills and interests. They also are used to track new contributi #### Help-Wanted Board -The pyOpenSci **Help-Wanted project board** is a organization level GitHub project board that provides a central place where contributors can +The pyOpenSci [**Help-Wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is a organization level GitHub project board that provides a central place where contributors can find tasks that pyOpenSci needs help with. We have two automated workflows setup for the help-wanted project board: @@ -87,22 +93,24 @@ for the help-wanted project board: * When an issue or pull request is closed, it is automatically archived from the project board. Tasks on this board are ideally smaller, well-defined, and can be completed or significantly advanced within the -duration of a sprint. The pyOpenSci Help-Wanted board is continuously updated to reflect -the current needs of pyOpenSci projects, making it easier for contributors to -jump in and start contributing. +duration of a sprint. The pyOpenSci Help-Wanted board should be updated throughout the year as new issues are opened in our organization GitHub repositories. Continual updates makes it easier for: + +* Contributors to jump in and start contributing and +* Sprint leaders to prepare for a sprint as the board will be more up to date. #### Annual Sprint Project Board At the start of each year, the pyOpenSci community manager creates a new Sprint -GitHub Project Board. The board will have several columns or statuses each or wchih represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: +GitHub Project Board. Here is an example of the [2024 sprint project board](https://github.com/orgs/pyOpenSci/projects/12). + +The board will have several columns or statuses each or which represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: * **Track issues and pull requests opened during a sprint event** * **Organize and Monitor Tasks**: Keep track of the progress of tasks during the sprint, ensuring clarity on which issues are being worked on and by whom. - **Manage the Triage Process**: Keep track of which pull requests have been addressed and merged and which ones still need attention. - **Calculate metrics**: Provide counts of activity that has occurred during a sprint event. -By using these boards, pyOpenSci ensures that sprints are organized, efficient, -and accessible to all participants. +By using these boards, pyOpenSci staff can easily keep tabs of sprint activities and outcomes. It also helps us ensure that all sprint issues and pull requests are addressed in a timely manner. ### Year Round Sprint tasks @@ -146,22 +154,23 @@ The current types of tasks in our board include: we should add content review and sphinx as a status options for people that review our guidebook, run through tutorials etc. ::: -:::{important} -If you are creating a new `help-wanted` issue it's critical that you include as much detailed information in the issue as possible. Imagine someone else reading the issue (that is not you!). In reading the issue, does an outside contributor have: +:::{admonition} Make sure issues contain specific detailed information before adding them to a project board +:class: important -* clearly understand the problem? (be specific, provide examples, links etc) -* have enough information to solve the problem? -* know exactly where the problem is occurring (provide links if you can or code examples ) -* have enough information needed to solve the problem? +If you are creating a new `help-wanted` issue, it's important to include as much detailed information in the issue as possible. Imagine someone else reading the issue (that is not you!). In reading the issue, does an outside contributor have: + +* enough information to understand the problem? (be specific, provide examples, links runnable code, broken github action runs) +* enough information to solve the problem? +* know exactly where the problem is occurring (provide links if you can or code examples) When in doubt, more information is always better! ::: Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a Sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. -### Pre-Sprint Event Tasks +## Pre-Sprint Event Tasks -#### Triage (Help-Wanted) Issues Across the pyOpenSci Organization +### Triage (Help-Wanted) Issues Across the pyOpenSci Organization Before a sprint begins, someone on the pyOpenSci team should go through and triage all of the open issues in the organization to determine: @@ -169,6 +178,7 @@ triage all of the open issues in the organization to determine: * Whether some of them are sprintable. * Whether they have enough specific and detailed information for someone to work on the issue without too much help during a sprint. +* Whether some open issues can be closed. This could be a small team exercise at a pre-meeting event held online for pyOpenSci staff and sprint community members (if there are any contributors @@ -181,23 +191,37 @@ questions during the sprint. If you have a table of 10-20 people sprinting for pyOpenSci, this means the person running the sprint will have less to do on-site! Sprints are busy—please add as much specific information as you can to each issue! -#### THIS LIKELY WON'T WORK Ensure issue and pull request templates are up to date +### Ensure issue and pull request templates are up to date -A challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues and pr's, during an event, every pyOpenSci GitHub repository should have a sprint issue and pull request template. Adding this template only needs to be completed once, however -if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a template. +A challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues, during an event, every pyOpenSci GitHub repository should have a sprint issue template. Adding this template only needs to be completed once. However, if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a sprint issue template. -The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a workflow on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. +The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a GitHub action on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. +:::{todo} +test this workflow: https://github.com/actions/add-to-project in a single repo NOTE - i'm not sure this will work. i forgot that pr templates are not as straight forward as issue templates are. issue templates are easier. +::: + +### Create a participant signup form + +* create the form +* create a dynamic qr code that we can update (the is placed on our table top cards ) OR get a card that we can add a sticker to with the code and replace the stickers... + + +:::{todo} + +jesse will develop this process with whatever platform we end up using... +::: + -### Tasks during a sprint +## Tasks during a sprint Below are tasks that should occur during a spring event. -#### Collect participant information +### Collect participant information The person running the event should collect information from participants -at the event via ______ **TODO insert how we do that here** _____. +at the event via ______ **TODO insert how we do that here** _____ following the process Jesse creates above.... * dynamic qr code... that people can scan. with small table top signs? * what do we collect? @@ -212,11 +236,11 @@ Where are the contributors from (country, place of work, other things??) ### Update the sprint issue and pull request board -During the event, the remote sprint support team (either community manager or a volunteer) , should +During the event, the remote sprint support team (either Community Manager or a volunteer), should: * label all issues and pull requests as `sprint-event` and with the label for the event - e.g. `pyconus-24` as they are opened. -* Once that the sprint-event label is applied to an issue or pr, they with automatically be added to the project sprint board. -* Finally, once on the sprint board, they can then move each issue and pull request to the event name status on the sprint board. +* Once that the `sprint-event` label is applied to an issue or pr, they with automatically be added to the project sprint board. +* Finally, once on the sprint board, they can then move each issue and pull request to the event name status on the sprint board. (this also can be done from the issue itself. ) This process, if done during the sprint, will make triaging issues and pull requests after the event, easier. @@ -227,10 +251,14 @@ Jesse adds a label for the event and moves it to a column ### Review and triage pull requests and issues -If you see small pull requests coming in that are clearly fixing things in a guidebook, please review them and approve if that makes sense. If -you see an issue opened that makes sense to work on, feel free to comment on it. +If you see small pull requests coming in that are clearly fixing things (typos, etc) in a guidebook, please review them and approve if that makes sense. If +you see an issue opened that makes sense to work on remotely with a participant, feel free to comment on it. -## Acknowledge spring contirbutors - All-Contributors Bot +:::{todo} +We will need to feel some of this out at scipy. +::: + +### Acknowledge sprint contributors - All-Contributors Bot pyOpenSci uses the [All-Contributors bot](https://allcontributors.org/docs/en/bot/usage) to recognize and celebrate the contributions of all our contributors. This bot @@ -239,24 +267,39 @@ easier to maintain accurate records of everyone's efforts. To add contributors to the repository using the All-Contributors bot: -1. **Use the Bot Command**: In a comment on an issue or pull request, use the following command to add a contributor as follows. +**Use the Bot Command**: In a comment on an issue or pull request, use the following command to add a contributor as follows. + `@all-contributors add @githubusername for ` - if they have opened an issue only, or reviewed an open pr use: +If they have opened an issue only, or reviewed an open pr use: `@all-contributors add @githubusername for review` - if they have opened a pull request use: + +If they have opened a pull request use: `@all-contributors add @githubusername for code, review` -2. **Merge PRs Individually**: The bot will create a pull request to update the -contributors list. Merge each All-Contributors PR individually and immediately -to avoid merge conflicts. +2. **Merge all-contributor bot Pull Requests Individually**: The bot will create a pull request to update the +contributors list when you call the commands above. IMPORTANT: Merge each all-Contributors bot pull request individually and immediately before adding another contributor to avoid merge conflicts. By recognizing contributors for their efforts, we foster a positive and inclusive community, encouraging more participation and collaboration. -## After a Sprint is complete +## After a Sprint tasks + +### Issue and PR triage +The biggest effort after a sprint will be triaging & addressing issues and pull requests that have been submitted during the sprint. This could take 1-2 weeks and up to a month depending on the scope of each change submitted. + +If there are new issues with no associated pull request, you can + +1. Invite the issue author to submit a pr if the change seems reasonable and they are up to the task. +2. If the issue is one that we agree should be addressed, then label the issue with `help-wanted` / `sprintable` so someone else can tackle it at our next pyOpenSci sprint. + +Review each pull request submitted (or invite community members to review) and determine if the pull request looks good as is or requires changes following the standard GitHub review process. + +Merge the pull request when it is complete and ready to be merged. + +### Followup thank you notes After a sprint, we will follow up with participants to show our appreciation and encourage continued engagement with the pyOpenSci community. Here are the key @@ -279,8 +322,8 @@ steps to take: - **Upcoming Events**: Inform participants about upcoming sprints, webinars, workshops, or any other events they might be interested in. -By taking these steps, you help maintain the momentum generated during the sprint, -foster a sense of community, and encourage ongoing contributions to pyOpenSci projects. +By thanking contributors you are helping to maintain the momentum generated during the sprint while also +fostering a sense of community, and encourage ongoing contributions to pyOpenSci projects. @@ -295,12 +338,15 @@ Community Content “owners” Related to above - help post event. We have a lot of issues and pr’s now. Can the community help with triage? -## Meeting Metrics that pyOpenSci collects -* Number of pr’s -* Number of issues -* Who contributed +:::{admonition} Meeting metrics that pyOpenSci collects +:class: info +* Number of pull request submitted +* Number of issues submitted +* Number of contributors contributed * Where are the contributors from (country, place of work, other things??) +::: + :::{todo} SPRINTS: Collecting information during - sprints, etc - process so we can work together? From 50a95183762bd2a4e17960eb93e922bb66f683e3 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 13:26:17 -0600 Subject: [PATCH 37/52] Edits from @kiersi Co-authored-by: Jesse Mostipak --- community/events/intro.md | 26 ++++++++++++++------------ community/events/sprints.md | 2 +- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/community/events/intro.md b/community/events/intro.md index 6dbd38b..afca5ee 100644 --- a/community/events/intro.md +++ b/community/events/intro.md @@ -4,28 +4,28 @@ pyOpensci staff regularly attend community meetings (e.g. SciPy meeting, PyCon US, etc). If the meeting is in person, some of the staff may be in person at the event while the community manager / others might be supporting the event remotely. -In these instances asynchronous communication and sharing of documents in an organized way is critical. +In these instances, asynchronous communication and sharing of documents in an organized way is critical. ### Event documents -For every meeting, pyOpenSci staff should create a Google drive folder located in our pyos-shared drive where meeting documents are stored. These documents may include talk and workshop proposals, attendee signup lists, graphics use in social media and out reach posts and more content related to the event. +For every meeting, pyOpenSci staff should create a Google Drive folder, located in our pyos-shared drive, where meeting documents will be stored. These documents may include talk and workshop proposals, attendee signup lists, graphics used in social media and outreach posts and more content related to the event. Before an event, pyOpenSci staff will make sure this folder is shared and supporting documents are added to it. Often the folder will be created prior to the event to store talk, Bof (birds of a feather), townhall and workshop proposals. :::{admonition} Team checkin prior to an event :class: note -Staff should also have a short check-in prior to an event to ensure that all documents, and elements needed for the event are shared, in the right place, etc. +Staff should also have a short check-in prior to an event to ensure that all documents, and elements needed for the event, are shared in the right place, appropriate permissions are granted, remote support needs for the event are clarified, etc. Because the internet might be an issue sometimes at an event, whomever is leading the event should always bring a pen and paper. ::: ## Event social media and graphics -The community manager will manage online “coms” and social media during an event. However it will be important for whomever is attending the event in person to be in asynchronous communication via the pyOpenSci Slack about key activities, findings, new cool things, etc to be posting about, promoting and highlighting. +The community manager will manage online “comms” and social media during an event. However, it is important for whomever is attending the event in person to be in asynchronous communication via the pyOpenSci Slack about key activities, findings, new cool things, etc. to be posting about, promoting and highlighting. -In some cases an event might “pop up” last minute - such as an Open Space at pyCon. In this case, the person attending the event may want to modify and reuse graphics posted on social media to publicize the event. +In some cases, an event might “pop up” last minute--such as an Open Space at PyCon. In this case, the person attending the event may want to modify and reuse graphics posted on social media to publicize the event. -To support this case, we should also create an event folder in our online graphics platform, Canva. This event specific folder will be where we store all graphics used to promote an event both before during and after in one place. This will make it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event or change in plans, as needed. +To support this case, an event folder in our online graphics platform, Canva, should be created prior to the event and shared with the pyOpenSci team. This event-specific folder will be where all graphics used to promote an event, both before, during and after, are stored. Using Canva as a central location for graphics makes it easier for the person at the event to make a quick change to a graphic, add a room number or a time for a pop up event, notify of any change in plans, etc. as needed. :::{admonition} Share the Canva folder with the pyopensci-canva-team :class: important @@ -36,17 +36,19 @@ Please also be sure to name files using expressive words that make them easy to ### Preparation prior to an event -Prior to an, in-person sprint, you should have the following things created: +Prior to an in-person sprint, the following items should be created: -1. A template "sign up" form with data fields that we collect from participants. This allows us to track who attends and event and to followup with them after (if they wish to have communication with us after) +1. A template "sign up" form, created in HubSpot and shared via a bit.ly shortlink, with data fields that we collect from participants. This allows us to track who attends and event and to followup with them after (if they wish to have communication with us after) 1. A tabletop “card” that says pyOpenSci. You will need 2-3 cards on hand for any event in case participants are spread across a few tables. This card will be important for events like sprints, workshops and open spaces where pyOpenSci has one or more tables in a large room. It will signal to contributors that we are there and help people quickly find us. - * The card should have a qr code that is dynamic (so we can update the url that it points to and reuse the cards). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank message to each participant using a mail-merge system. + * The card should have a qr code that is dynamic (so we can update the url that it points to and reuse the cards). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank you message to each participant using MailChimp or HubSpot. :::{todo} will this work for events as we will want an event name associated with it but it would be annoying to make a new card for every event? UNLESS we make a bunch at once for all events for the year? -And maybe a banner for a door if I'm running a workshop? -the table top thing looks like this: https://www.officedepot.com/a/products/5760240/American-Metalcraft-Stainless-Steel-Harp-Style/ (this is better than acrylic because it won't break, but we could do plastic if you prefer). +We are currently pricing out a travel banner, to be used outside a space where pyOpenSci is running a workshop. +An example of the [base/holder for the table top card](https://www.officedepot.com/a/products/5760240/American-Metalcraft-Stainless-Steel-Harp-Style/). We'll initially test out metal, as they will be less likely to break in transit, however acrylic options are also available. -we'd then print out (and laminate?) some kind of card that has the pyOpenSci logo, website, and a QR code that links to all of our socials//mailing list. this way it'll give people a visual cue as to where pyOS is congregating, as well as the option to interact with us directly. +Cards will be designed and printed, all of which will contain, at minimum, the pyOpenSci logo, website address, and a QR code that links to all of our socials/mailing list. this way it'll give people a visual cue as to where pyOS is congregating, as well as the option to interact with us directly. + +Cards will be designed to be printed out on a home printer, or through MOO, and laminated when non-glossy paper is used. ::: diff --git a/community/events/sprints.md b/community/events/sprints.md index 33e351c..6e8c4e3 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -6,7 +6,7 @@ :::{admonition} TL;DR -**Before sprint** +**Before a sprint** * Go through the pyOPenSci repo issues and ensure all relevant help-wanted / sprintable issues have labels and are on the project board. * Also ensure all issues on the project board have enough specific information for a new user to follow and complete the task needed to be done. From 973dd9088ce03f3f9cd0c198f41151d905c8aa0b Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 13:34:48 -0600 Subject: [PATCH 38/52] Fix: Edits from @kiersi Co-authored-by: Jesse Mostipak --- community/events/sprints.md | 58 +++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index 6e8c4e3..8031574 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -10,13 +10,15 @@ * Go through the pyOPenSci repo issues and ensure all relevant help-wanted / sprintable issues have labels and are on the project board. * Also ensure all issues on the project board have enough specific information for a new user to follow and complete the task needed to be done. -**During sprint** +**During a sprint** * label all newly submitted issues as sprint-event, sprint-name-year -* merge small pr's that are clearly typo fixies, easy to review things -* add contributors as contributors to the repo using the all contributors bot @all-contributors add @githubusername for code, review (for an issue use review for a pr use code, review ). Merge each all contributor pr individually and immediately to avoid merge conflicts +* merge small PRs that are clearly typo fixes and other easy to review things +* for PRs, add contributors to the repo using the all contributors bot, with the format `@all-contributors add @githubusername for code, review` +* for an issue use review for a pr use code, review ). +* merge each all contributor PR individually and immediately to avoid merge conflicts -**After Sprint** +**After a Sprint** ::: @@ -28,7 +30,7 @@ There are three types of pyOpenSci sprint events: 1. **Community Sprint Events**: pyOpenSci hosts these at meetings it attends, such as PyCon US and the SciPy meeting. 2. **Online Sprint Events**: pyOpenSci may hold its own sprint events online to encourage global contributions. -3. **Community-Hosted Sprint Events**: Contributors and community members host pyOpenSci sprint events at meetings they attend. +3. **Community-hosted Sprint Events**: Contributors and community members host pyOpenSci sprint events at meetings they attend. During pyOpenSci sprints, contributors need tasks that are “sprintable.” Sprintable tasks are those that can be worked on and potentially completed (or @@ -50,14 +52,14 @@ pyOpenSci uses a combination of GitHub project boards and user surveys to track ## Sprint Participant Motivations -Sprint participants are often motivated by different things: +Sprint participants are often motivated by different things. Some come to: -* Some come to learn. -* Some come to help and support a project they care about. -* Some come to connect and build community. +* learn +* help and support a project they care about +* connect and build community pyOpenSci supports and empowers all of these motivations, with an emphasis on -empowering contributors who are newer to contributing while greatly benefiting +empowering contributors who are newer to contributing, while greatly benefiting from more experienced sprinters who can help move the organization forward. ### pyOpenSci sprints are accessible @@ -85,7 +87,7 @@ that suit their skills and interests. They also are used to track new contributi #### Help-Wanted Board -The pyOpenSci [**Help-Wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is a organization level GitHub project board that provides a central place where contributors can +The pyOpenSci [**Help-Wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is an organization-level GitHub project board that provides a central place where contributors can find tasks that pyOpenSci needs help with. We have two automated workflows setup for the help-wanted project board: @@ -103,7 +105,7 @@ duration of a sprint. The pyOpenSci Help-Wanted board should be updated througho At the start of each year, the pyOpenSci community manager creates a new Sprint GitHub Project Board. Here is an example of the [2024 sprint project board](https://github.com/orgs/pyOpenSci/projects/12). -The board will have several columns or statuses each or which represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: +The board will have several columns or statuses, each of which represents the name of a sprint event (example: pyconus-2024, scipy-2024, fall-festival-2024. This board is used to: * **Track issues and pull requests opened during a sprint event** * **Organize and Monitor Tasks**: Keep track of the progress of tasks during the sprint, ensuring clarity on which issues are being worked on and by whom. @@ -121,22 +123,22 @@ these items as they pop up, you are saving time spent in preparing for a sprint. pyOpenSci uses the GitHub [help-wanted project board](https://github.com/orgs/pyOpenSci/projects/3) to keep track of tasks that volunteers can assist with. When you see an issue -opened or if you open an issue yourself in any of our GitHub repositories within +opened, or if you open an issue yourself in any of our GitHub repositories within our [pyOpenSci GitHub organization](https://www.github.com/pyopensci), always consider whether the issue is something that someone else could help us with. If the issue is something that someone else in the community could do: -1. **Add a `help-wanted` Label**: Any issue or pull request with the `help-wanted` +1. **Add a `help-wanted` Label**: any issue or pull request with the `help-wanted` label in our organization will be automatically added to our [pyOpenSci help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). -2. **Add a `sprintable` Label (if applicable)**: If the task could be completed +2. **Add a `sprintable` Label (if applicable)**: if the task could be completed during a sprint (meaning it is something that could be completed within an hour and up to a single day's worth of work), also add the label `sprintable` to the issue. -3. **Update the Status on the Project Board**: Once the issue has been added to +3. **Update the Status on the Project Board**: once the issue has been added to the project board (it normally takes our CI workflow 30 seconds to a minute), update the status of the issue on the project board based on the type of skill needed. @@ -148,13 +150,13 @@ The current types of tasks in our board include: * Beginner friendly / non technical * Dev Ops / GitHub actions (Continuous Integration) * Python programming - * Website - css or ruby + * Website - CSS or Ruby :::{todo} we should add content review and sphinx as a status options for people that review our guidebook, run through tutorials etc. ::: -:::{admonition} Make sure issues contain specific detailed information before adding them to a project board +:::{admonition} Make sure issues contain specific, detailed information before adding them to a project board :class: important If you are creating a new `help-wanted` issue, it's important to include as much detailed information in the issue as possible. Imagine someone else reading the issue (that is not you!). In reading the issue, does an outside contributor have: @@ -166,7 +168,7 @@ If you are creating a new `help-wanted` issue, it's important to include as much When in doubt, more information is always better! ::: -Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a Sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. +Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. ## Pre-Sprint Event Tasks @@ -193,7 +195,7 @@ Sprints are busy—please add as much specific information as you can to each is ### Ensure issue and pull request templates are up to date -A challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues, during an event, every pyOpenSci GitHub repository should have a sprint issue template. Adding this template only needs to be completed once. However, if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a sprint issue template. +One challenge of a successful sprint is that there will be many issues and pull requests to triage after the sprint. To keep track of new issues during an event, every pyOpenSci GitHub repository should have a sprint issue template. Adding this template only needs to be completed once. However, if there is a new pyOpenSci Github repository (this rarely happens), make sure that repo has a sprint issue template. The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a GitHub action on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. @@ -216,7 +218,7 @@ jesse will develop this process with whatever platform we end up using... ## Tasks during a sprint -Below are tasks that should occur during a spring event. +Below are tasks that should occur during a sprint event. ### Collect participant information @@ -229,7 +231,7 @@ at the event via ______ **TODO insert how we do that here** _____ following the Metrics – -Number of pr’s +Number of PRs Number of issues Who contributed Where are the contributors from (country, place of work, other things??) @@ -290,9 +292,9 @@ community, encouraging more participation and collaboration. ### Issue and PR triage The biggest effort after a sprint will be triaging & addressing issues and pull requests that have been submitted during the sprint. This could take 1-2 weeks and up to a month depending on the scope of each change submitted. -If there are new issues with no associated pull request, you can +If there are new issues with no associated pull request, you can: -1. Invite the issue author to submit a pr if the change seems reasonable and they are up to the task. +1. Invite the issue author to submit a PR if the change seems reasonable and they are up to the task. 2. If the issue is one that we agree should be addressed, then label the issue with `help-wanted` / `sprintable` so someone else can tackle it at our next pyOpenSci sprint. Review each pull request submitted (or invite community members to review) and determine if the pull request looks good as is or requires changes following the standard GitHub review process. @@ -310,19 +312,19 @@ steps to take: 2. **Provide Feedback**: Include any relevant feedback or outcomes from the sprint. This could involve sharing metrics, such as the number of issues closed, pull requests merged, or any specific contributions that stood out. 3. **Invite Continued Engagement**: - - **Newsletter**: Encourage participants to subscribe to the pyOpenSci newsletter + - **Newsletter**: Encourage participants to subscribe to the [pyOpenSci newsletter](https://eepurl.com/iM7SOM) to stay updated on future events, news, and opportunities. - - **LinkedIn**: Invite them to follow pyOpenSci on LinkedIn for professional updates + - **LinkedIn**: Invite them to follow [pyOpenSci on LinkedIn](https://www.linkedin.com/company/pyopensci) for professional updates and community highlights. - **GitHub**: Remind them to continue following and contributing to pyOpenSci - repositories on GitHub. + [repositories on GitHub](https://github.com/pyopensci). - Discourse? 4. **Stay Connected**: - **Upcoming Events**: Inform participants about upcoming sprints, webinars, workshops, or any other events they might be interested in. -By thanking contributors you are helping to maintain the momentum generated during the sprint while also +By thanking contributors you are helping to maintain the momentum generated during the sprint, while also fostering a sense of community, and encourage ongoing contributions to pyOpenSci projects. From 285bcd87bf1b1c8d7ed414e9683ed0c28ac9ff2b Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 15:45:03 -0600 Subject: [PATCH 39/52] Fix: edits from review --- community/events/sprints.md | 103 ++++++++++++++++++++++-------------- conf.py | 4 +- 2 files changed, 66 insertions(+), 41 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index 8031574..b0a348c 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -1,4 +1,4 @@ -# pyOpenSci sprints +# pyOpenSci Sprints :::{todo} * TODO: https://github.com/actions/add-to-project?tab=readme-ov-file i think we want to set this up for all repos so this works for scipy. @@ -7,19 +7,24 @@ :::{admonition} TL;DR **Before a sprint** -* Go through the pyOPenSci repo issues and ensure all relevant help-wanted / sprintable issues have labels and are on the project board. -* Also ensure all issues on the project board have enough specific information for a new user to follow and complete the task needed to be done. + +* pyOpenSci staff go through the pyOpenSci repo issues and ensure all relevant **help-wanted** and/or **sprintable** both have appropriated labels and have been added to the the project board in the appropriate column (beginner-friendly, python, dev-ops/ci, Python, Sphinx). +* pyOpenSci staff ensure all issues on the project board have enough **specific** information for a new user to follow and complete the task needed to be done. The more specific the issue is, the fewer questions a sprinter / contributor will ask during a sprint. This saves significant time and energy for both the sprint attendee and whomever is leading the sprint. **During a sprint** -* label all newly submitted issues as sprint-event, sprint-name-year -* merge small PRs that are clearly typo fixes and other easy to review things -* for PRs, add contributors to the repo using the all contributors bot, with the format `@all-contributors add @githubusername for code, review` -* for an issue use review for a pr use code, review ). -* merge each all contributor PR individually and immediately to avoid merge conflicts +* Label all newly submitted issues as `sprint-event`, `sprint-name-year` (example: `sprint`, `pyconus-24`) +* Merge small PRs that are clearly mergeable without significant review. Examples might include: typo fixes and other easy-to- review contributions. +* For PRs, add contributors to the GitHub repository that they contributed to using the [All Contributors bot](https://allcontributors.org/) using the command: `@all-contributors add @githubusername for code, review` (if the contribution is a pull request) or `@all-contributors add @githubusername for review` (if the contribution is an issue +* **IMPORTANT:** Merge each all-contributor-bot PR's individually and immediately after they have been opened to avoid merge conflicts -**After a Sprint** +**After a sprint** +* Triage issues and pull requests +* Make sure all contributors have been added to each repo they've contributed to using the all-contributors bot. +* Focus on replying, addressing and merging pull requests as we can. If an issue has a lingering TODO - consider tagging it with a `help-wanted` label for a future sprint. +* Send followup *thank you for participating* notes +* Collect / process / aggregate sprint metrics ::: @@ -50,7 +55,7 @@ beneficial when we write grants and solicit sponsorships. pyOpenSci uses a combination of GitHub project boards and user surveys to track participation and success metrics. More on that below. -## Sprint Participant Motivations +## What motivates sprint participants? Sprint participants are often motivated by different things. Some come to: @@ -58,9 +63,11 @@ Sprint participants are often motivated by different things. Some come to: * help and support a project they care about * connect and build community -pyOpenSci supports and empowers all of these motivations, with an emphasis on -empowering contributors who are newer to contributing, while greatly benefiting -from more experienced sprinters who can help move the organization forward. +pyOpenSci supports and empowers all of the above motivations. We thrive on empowering new +empowering contributors to make their first (or second) contributions! This impact aligns well with our mission. We also greatly benefit +from more experienced sprinters who can help move the organization's infrastructure and needs forward. + +Sprints are always a win/win for pyOpenSci. ### pyOpenSci sprints are accessible @@ -68,26 +75,35 @@ It's important to pyOpenSci's mission that sprints are accessible to both new and seasoned contributors. We aim to ensure that all participants have a successful experience with our community. Some participants are new and are submitting their first-ever issue and/or pull request to an open source project. -These participants may need help using git and GitHub, or they may feel -intimidated by their first contribution. Others are more experienced and +These participants: + +* may need help using git and GitHub, or +* they may feel intimidated by their first contribution (but they want to try!). + +Others are more experienced and comfortable in a sprint environment but may have questions about more technical -open issues and the outcomes that pyOpenSci wants to see for issue solutions. +open issues and the outcomes that pyOpenSci wants to see in issue solutions. Supporting all of these participants is crucial to our mission and can require significant effort during a sprint event. -As such, it's important for anyone leading a sprint to come prepared! In some cases having community helpers will go along way to supporting beginner contributor success. - +As such, it's important for anyone leading a sprint to come prepared! In most cases having community helpers will go along way to supporting beginner contributor success. -## Sprint Infrastructure - GitHub Project Boards +## Sprint infrastructure - GitHub projects To efficiently manage and track contributions during sprints, pyOpenSci utilizes -GitHub project boards. These boards help us organize tasks that participants can work on. This ensures that +[GitHub projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). We use projects to organize issues and pull requests that contributors could potentially address during or outside of a sprint. Tasks that are discrete enough to complete during a sprint are labeled with the `sprintable` label. + +An organized project ensures that contributors, whether new or experienced, can easily find and work on tasks -that suit their skills and interests. They also are used to track new contributions that we get during an event. +that suit their skills and interests. -#### Help-Wanted Board +:::{not} +We also are testing out using [event projects](https://github.com/orgs/pyOpenSci/projects/12) to to track new contributions in the form of pull requests and issues that we receive during an event such as a PyCon US or SciPy sprint. +::: + +#### Help-wanted board -The pyOpenSci [**Help-Wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is an organization-level GitHub project board that provides a central place where contributors can +The pyOpenSci [**help-wanted project board**](https://github.com/orgs/pyOpenSci/projects/3) is an organization-level GitHub project board that provides a central place where contributors can find tasks that pyOpenSci needs help with. We have two automated workflows setup for the help-wanted project board: @@ -95,12 +111,12 @@ for the help-wanted project board: * When an issue or pull request is closed, it is automatically archived from the project board. Tasks on this board are ideally smaller, well-defined, and can be completed or significantly advanced within the -duration of a sprint. The pyOpenSci Help-Wanted board should be updated throughout the year as new issues are opened in our organization GitHub repositories. Continual updates makes it easier for: +duration of a sprint. The pyOpenSci help-wanted board should be updated throughout the year as new issues are opened in our organization GitHub repositories. Continual updates makes it easier for: * Contributors to jump in and start contributing and * Sprint leaders to prepare for a sprint as the board will be more up to date. -#### Annual Sprint Project Board +#### Tracking annual contributions: the sprint project board At the start of each year, the pyOpenSci community manager creates a new Sprint GitHub Project Board. Here is an example of the [2024 sprint project board](https://github.com/orgs/pyOpenSci/projects/12). @@ -114,12 +130,12 @@ The board will have several columns or statuses, each of which represents the na By using these boards, pyOpenSci staff can easily keep tabs of sprint activities and outcomes. It also helps us ensure that all sprint issues and pull requests are addressed in a timely manner. -### Year Round Sprint tasks +### Year round sprint tasks Below are tasks to stay on top of throughout the year. By working on these items as they pop up, you are saving time spent in preparing for a sprint. -#### Maintain the the pyOpenSci help-wanted project board +#### Maintain the pyOpenSci help-wanted project board pyOpenSci uses the GitHub [help-wanted project board](https://github.com/orgs/pyOpenSci/projects/3) to keep track of tasks that volunteers can assist with. When you see an issue @@ -168,11 +184,11 @@ If you are creating a new `help-wanted` issue, it's important to include as much When in doubt, more information is always better! ::: -Labeling issues with `help-wanted` / `sprintable` throughout the year as they are opened will save significant preparation time when a sprint event arises. It will also make it easier for fly-by contributors to find things to help us with throughout the year. +It is important to label issues with `help-wanted` / `sprintable` throughout the year and as they are opened as we can. This will save significant when preparing for a sprint. It will also make it easier for fly-by contributors to find things to help us with throughout the year. -## Pre-Sprint Event Tasks +## Pre-sprint tasks -### Triage (Help-Wanted) Issues Across the pyOpenSci Organization +### Triage (help-wanted) issues across the pyOpenSci organization Before a sprint begins, someone on the pyOpenSci team should go through and triage all of the open issues in the organization to determine: @@ -200,18 +216,22 @@ One challenge of a successful sprint is that there will be many issues and pull The sprint template will auto-populate a `sprint-event` label on the issue or pull request when it is opened. We will then setup a GitHub action on the sprint project board for that year to auto-add any issue or pull request with the `sprint-event` label on it to the sprint project board. :::{todo} -test this workflow: https://github.com/actions/add-to-project in a single repo -NOTE - i'm not sure this will work. i forgot that pr templates are not as straight forward as issue templates are. issue templates are easier. +NOTE: i have setup this workflow https://github.com/actions/add-to-project on most (but not all) of our repos now. so it does handle moving help-wanted issues to the project. BUT it is hard to think about events. This is because there is no easy to use pull request template. so while we could automagically update a workflow before an event we'd have to do it for every event AND it would only work on issues - not pull requests. As such my idea of automating event tags won't work. + +For now - we should do that manually during the event. It would be an easy enough thing for jesse to do remotely i think? or i could do it IF the sprint slows down. it really didn't at pycon this year (2024) ::: + + +:::{todo} + +Jesse will flesh this out when it's ready! + ### Create a participant signup form * create the form * create a dynamic qr code that we can update (the is placed on our table top cards ) OR get a card that we can add a sticker to with the code and replace the stickers... - -:::{todo} - jesse will develop this process with whatever platform we end up using... ::: @@ -222,6 +242,8 @@ Below are tasks that should occur during a sprint event. ### Collect participant information +*This section will be fleshed out soon...* +:::{todo} The person running the event should collect information from participants at the event via ______ **TODO insert how we do that here** _____ following the process Jesse creates above.... @@ -229,13 +251,14 @@ at the event via ______ **TODO insert how we do that here** _____ following the * what do we collect? * how do they opt out of future coms? - -Metrics – +What Metrics do we collect and how? Number of PRs Number of issues Who contributed Where are the contributors from (country, place of work, other things??) +::: + ### Update the sprint issue and pull request board During the event, the remote sprint support team (either Community Manager or a volunteer), should: @@ -247,7 +270,7 @@ During the event, the remote sprint support team (either Community Manager or a This process, if done during the sprint, will make triaging issues and pull requests after the event, easier. :::{todo} -We create one issue and pr template that we can use across all our repos – it has a label that automatically will be added to the board with “no status” +We create one issue and pull requesttemplate that we can use across all our repos – it has a label that automatically will be added to the board with “no status” Jesse adds a label for the event and moves it to a column ::: @@ -273,7 +296,7 @@ To add contributors to the repository using the All-Contributors bot: `@all-contributors add @githubusername for ` -If they have opened an issue only, or reviewed an open pr use: +If they have opened an issue only, or reviewed an open pull request use: `@all-contributors add @githubusername for review` @@ -287,7 +310,7 @@ contributors list when you call the commands above. IMPORTANT: Merge each all-Co By recognizing contributors for their efforts, we foster a positive and inclusive community, encouraging more participation and collaboration. -## After a Sprint tasks +## After a sprint tasks ### Issue and PR triage The biggest effort after a sprint will be triaging & addressing issues and pull requests that have been submitted during the sprint. This could take 1-2 weeks and up to a month depending on the scope of each change submitted. diff --git a/conf.py b/conf.py index d7ec7e0..65fbd6b 100644 --- a/conf.py +++ b/conf.py @@ -29,7 +29,9 @@ # Get the latest Git tag - there might be a prettier way to do this but... try: release_value = ( - subprocess.check_output(["git", "describe", "--tags"]).decode("utf-8").strip() + subprocess.check_output(["git", "describe", "--tags"]) + .decode("utf-8") + .strip() ) release_value = release_value[:4] except subprocess.CalledProcessError: From 56dd6226fe9b9fa1b38ef3bf5afe2920a54c7b6e Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 15:53:19 -0600 Subject: [PATCH 40/52] Final edits --- community/events/sprints.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index b0a348c..c791bea 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -341,7 +341,9 @@ steps to take: and community highlights. - **GitHub**: Remind them to continue following and contributing to pyOpenSci [repositories on GitHub](https://github.com/pyopensci). +:::{todo} - Discourse? +::: 4. **Stay Connected**: - **Upcoming Events**: Inform participants about upcoming sprints, webinars, @@ -350,26 +352,29 @@ steps to take: By thanking contributors you are helping to maintain the momentum generated during the sprint, while also fostering a sense of community, and encourage ongoing contributions to pyOpenSci projects. +### Final wrap up activities +We will have several outcome tasks to do to wrap up a sprint. These +are listed below: +* Blog post about the event with stats around activity (number of participants, pull requests, issues, etc). This post might highlight wins both big and "small"! +* Social media promoting the success of the event and above metrics +* LinkedIn newsletter reusing that blog post content +### Welcome new contributors to slack -Help for sprint event triage after the event -Event outputs -Blog post(s) -Social -Welcome new ppl to slack -Community Content “owners” -Related to above - help post event. We have a lot of issues and pr’s now. Can the community help with triage? - - +Because some participants come to sprints to learn, they may not stage engaged with pyOpenSci after a sprint event. As such it's best to invite +people who continue to stay engaged with us either via GitHub or some +other mechanism (becoming a reviewer, editor, submitting a package, etc). :::{admonition} Meeting metrics that pyOpenSci collects :class: info * Number of pull request submitted * Number of issues submitted * Number of contributors contributed - * Where are the contributors from (country, place of work, other things??) + * Where are the contributors from (country, place of work / organization) + * Type of user - student, professional, non profit/ public sector. + * Optional - demographics ::: From 0891af59a53871c1b8fa6871727fcb3d539e73f2 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 15:57:13 -0600 Subject: [PATCH 41/52] Fix: pre-commit --- community/events/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/community/events/intro.md b/community/events/intro.md index afca5ee..a2decfc 100644 --- a/community/events/intro.md +++ b/community/events/intro.md @@ -45,7 +45,7 @@ Prior to an in-person sprint, the following items should be created: :::{todo} will this work for events as we will want an event name associated with it but it would be annoying to make a new card for every event? UNLESS we make a bunch at once for all events for the year? -We are currently pricing out a travel banner, to be used outside a space where pyOpenSci is running a workshop. +We are currently pricing out a travel banner, to be used outside a space where pyOpenSci is running a workshop. An example of the [base/holder for the table top card](https://www.officedepot.com/a/products/5760240/American-Metalcraft-Stainless-Steel-Harp-Style/). We'll initially test out metal, as they will be less likely to break in transit, however acrylic options are also available. Cards will be designed and printed, all of which will contain, at minimum, the pyOpenSci logo, website address, and a QR code that links to all of our socials/mailing list. this way it'll give people a visual cue as to where pyOS is congregating, as well as the option to interact with us directly. From 2c2247141375c4be596fc487c685e5189ea99dd1 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 7 Jun 2024 17:08:05 -0600 Subject: [PATCH 42/52] Add links to tldr --- community/events/sprints.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/community/events/sprints.md b/community/events/sprints.md index c791bea..65ee113 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -8,14 +8,14 @@ **Before a sprint** -* pyOpenSci staff go through the pyOpenSci repo issues and ensure all relevant **help-wanted** and/or **sprintable** both have appropriated labels and have been added to the the project board in the appropriate column (beginner-friendly, python, dev-ops/ci, Python, Sphinx). +* pyOpenSci staff go through the pyOpenSci repo issues and ensure all relevant **help-wanted** and/or **sprintable** both have appropriated labels and have been added to the the [GitHub project](github-project) in the appropriate column (beginner-friendly, python, dev-ops/ci, Python, Sphinx). * pyOpenSci staff ensure all issues on the project board have enough **specific** information for a new user to follow and complete the task needed to be done. The more specific the issue is, the fewer questions a sprinter / contributor will ask during a sprint. This saves significant time and energy for both the sprint attendee and whomever is leading the sprint. **During a sprint** * Label all newly submitted issues as `sprint-event`, `sprint-name-year` (example: `sprint`, `pyconus-24`) * Merge small PRs that are clearly mergeable without significant review. Examples might include: typo fixes and other easy-to- review contributions. -* For PRs, add contributors to the GitHub repository that they contributed to using the [All Contributors bot](https://allcontributors.org/) using the command: `@all-contributors add @githubusername for code, review` (if the contribution is a pull request) or `@all-contributors add @githubusername for review` (if the contribution is an issue +* For PRs, add contributors to the GitHub repository that they contributed to using the [All Contributors bot](https://allcontributors.org/) using the command: `@all-contributors add @githubusername for code, review` (if the contribution is a pull request) or `@all-contributors add @githubusername for review` (if the contribution is an issue). [More on using the bot here.](all-contribs) * **IMPORTANT:** Merge each all-contributor-bot PR's individually and immediately after they have been opened to avoid merge conflicts **After a sprint** @@ -88,6 +88,7 @@ significant effort during a sprint event. As such, it's important for anyone leading a sprint to come prepared! In most cases having community helpers will go along way to supporting beginner contributor success. +(github-project)= ## Sprint infrastructure - GitHub projects To efficiently manage and track contributions during sprints, pyOpenSci utilizes @@ -283,6 +284,7 @@ you see an issue opened that makes sense to work on remotely with a participant, We will need to feel some of this out at scipy. ::: +(all-contribs)= ### Acknowledge sprint contributors - All-Contributors Bot pyOpenSci uses the [All-Contributors bot](https://allcontributors.org/docs/en/bot/usage) From 3f1a7c6617973755130f9a2fc00fa75a0a4e82bb Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Mon, 12 Aug 2024 16:16:44 -0600 Subject: [PATCH 43/52] add: readme for exec council notes --- reference/meeting-notes/executive-council/README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 reference/meeting-notes/executive-council/README.md diff --git a/reference/meeting-notes/executive-council/README.md b/reference/meeting-notes/executive-council/README.md new file mode 100644 index 0000000..d2d320b --- /dev/null +++ b/reference/meeting-notes/executive-council/README.md @@ -0,0 +1 @@ +## Executive council meeting notes From 4b3cf4f8597b011517991466a6e19f75f736c707 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 31 May 2024 17:05:47 -0600 Subject: [PATCH 44/52] Add: page on github issues in our org --- community/github/issues.md | 82 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 community/github/issues.md diff --git a/community/github/issues.md b/community/github/issues.md new file mode 100644 index 0000000..cd31d12 --- /dev/null +++ b/community/github/issues.md @@ -0,0 +1,82 @@ +# pyOpenSci GitHub issue process + +When possible, pull request and issue submissions and reviews should follow +standard open source workflows. Below are guidelines for handling issues. + +## Guidelines for New Issues + + +**Issues in should be as specific as possible:** specifics within an issue help both our future selves and also outside contributors understand the goal or +desired outcome associated with addressing the issue. This is important both internally and for issues that we tag as `help-wanted`, which we hope community members will address in pyOpenSci sprints. + +To ensure an issue is well-written and specific, include the following details: + +- **Clear Title:** A concise and descriptive title summarizing the issue or feature request helps us scan through issues and understand what each issue is about. Below are some example titles that are specific + + * `Bug: broken link in link-to-page-here / name of page / document etc` + * `Fix: confusing paragraph on Python packaging with Hatch` + * `Add: page on using pixi for dependencies` + +- **Description:** A detailed explanation of the issue or feature request, including context, background information, and the reason for the request. Explain why the issue is important and what problem it solves. + +- **Screenshots/Code Samples:** Screenshots, code snippets, links, or any other relevant files that can help in understanding the issue better. + +- **Possible Solutions/Recommendations:** Any ideas or suggestions for how to address the issue, which can help guide contributors towards a solution. + +- **Related Issues or Pull Requests:** References to any related issues or pull requests, providing additional context and understanding of the broader scope of the issue. + +### If you are reporting a code bug + +* **Steps to Reproduce (for bugs):** A step-by-step guide on how to reproduce the issue, including relevant code snippets, commands, or configurations. + +* **Expected vs. Actual Behavior (for bugs):** A description of what you expected to happen and what actually happened. This helps in understanding the discrepancy and the impact of the bug. + +* **Environment Details (for bugs):** Details about the environment where the issue was observed, such as operating system, Python version, library versions, and any other relevant software/hardware details. + +### If you have permissions, label the issue + +While outside contributors will not have permission to label issues, pyOpenSci core team members and volunteers will. Be sure to add appropriate labels to +issues to make it easier to triage them. + +## Help-wanted / sprintable issues + +If an issue is something that anyone in the community could potentially +address, it's ideal to label the issue with `help-wanted` and/or `sprintable`. +A sprintable issue refers to an issue that could be completed or worked on +during a 1-2 day sprint, thus it should be smaller and more confined in scope. +A help-wanted issue is one that anyone is welcome to work on during whatever +time they have available. + +Once the `help-wanted` or `sprintable` issue label is added, the issue will be +automatically added to our +[pyOpenSci help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). +This automation is implemented currently for a single repository (the packaging guide) but we plan to implement it for other repositories using the add-to-project GitHub action. + + +:::{note} +The issue will be archived from the project board once it is closed. +::: + + +:::{todo} +Add link to sprints page when it's online +::: + +If an issue is unclear, a pyOpenSci staff member or designated community +member can ask the issue author to provide more information. + + + + + + +:::{todo} +Add section on labels +::: + +## Issue Maintenance + +Our goal at pyOpenSci is to keep our list of issues current and active. +Quarterly issue cleanup sessions should be implemented to ensure issues are +either being actively addressed or to assess whether older or stale issues can +be potentially closed. From 25af06f6f5aa0192522dd62f8e3935aefbde4297 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 13 Aug 2024 13:21:15 -0600 Subject: [PATCH 45/52] Fix: edits from @kiersi Co-authored-by: Jesse Mostipak --- community/github/issues.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/community/github/issues.md b/community/github/issues.md index cd31d12..afa729b 100644 --- a/community/github/issues.md +++ b/community/github/issues.md @@ -1,12 +1,12 @@ # pyOpenSci GitHub issue process -When possible, pull request and issue submissions and reviews should follow +When possible, pull requests, issue submissions and reviews should follow standard open source workflows. Below are guidelines for handling issues. ## Guidelines for New Issues -**Issues in should be as specific as possible:** specifics within an issue help both our future selves and also outside contributors understand the goal or +**Issues should be as specific as possible:** specifics within an issue help both our future selves and also outside contributors understand the goal or desired outcome associated with addressing the issue. This is important both internally and for issues that we tag as `help-wanted`, which we hope community members will address in pyOpenSci sprints. To ensure an issue is well-written and specific, include the following details: @@ -19,15 +19,15 @@ To ensure an issue is well-written and specific, include the following details: - **Description:** A detailed explanation of the issue or feature request, including context, background information, and the reason for the request. Explain why the issue is important and what problem it solves. -- **Screenshots/Code Samples:** Screenshots, code snippets, links, or any other relevant files that can help in understanding the issue better. +- **Screenshots/Code Samples:** Include screenshots, code snippets, links, or any other relevant files that can help others in understanding the issue better. -- **Possible Solutions/Recommendations:** Any ideas or suggestions for how to address the issue, which can help guide contributors towards a solution. +- **Possible Solutions/Recommendations:** It's helpful to provide any ideas or suggestions for how to address the issue, which can help guide contributors towards a solution. -- **Related Issues or Pull Requests:** References to any related issues or pull requests, providing additional context and understanding of the broader scope of the issue. +- **Related Issues or Pull Requests:** Add references to any related issues or pull requests, which provides additional context and understanding of the broader scope of the issue. ### If you are reporting a code bug -* **Steps to Reproduce (for bugs):** A step-by-step guide on how to reproduce the issue, including relevant code snippets, commands, or configurations. +* **Steps to Reproduce (for bugs):** A step-by-step guide (generally a list or narrative) on how to reproduce the issue, including relevant code snippets, commands, or configurations. * **Expected vs. Actual Behavior (for bugs):** A description of what you expected to happen and what actually happened. This helps in understanding the discrepancy and the impact of the bug. @@ -50,7 +50,7 @@ time they have available. Once the `help-wanted` or `sprintable` issue label is added, the issue will be automatically added to our [pyOpenSci help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). -This automation is implemented currently for a single repository (the packaging guide) but we plan to implement it for other repositories using the add-to-project GitHub action. +This automation is implemented currently for a single repository (the packaging guide), but we plan to implement it for other repositories using the add-to-project GitHub action. :::{note} @@ -77,6 +77,6 @@ Add section on labels ## Issue Maintenance Our goal at pyOpenSci is to keep our list of issues current and active. -Quarterly issue cleanup sessions should be implemented to ensure issues are -either being actively addressed or to assess whether older or stale issues can -be potentially closed. +Quarterly issue cleanup sessions are implemented to ensure issues are +either being actively addressed, or to assess whether older or stale issues can +potentially be closed. From 0eb44107b8e380857e8877ead60bd618e105789a Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 13 Aug 2024 13:38:12 -0600 Subject: [PATCH 46/52] fix: edits to gh issues page --- community/github/intro.md | 26 ++-------- community/github/issues.md | 97 ++++++++++++++++++++++---------------- community/index.md | 8 ++-- 3 files changed, 62 insertions(+), 69 deletions(-) diff --git a/community/github/intro.md b/community/github/intro.md index db69213..ed4ec42 100644 --- a/community/github/intro.md +++ b/community/github/intro.md @@ -1,19 +1,7 @@ -# GitHub +# pyOpenSci GitHub Processes -:::{toctree} -:glob: -:maxdepth: 2 - -* -::: - -:::{todo} -1. for extra contributors - A pyOpenSci community member will review your post / contribution. you don't need to request a review. -1. -::: - - -pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci processes and content including: +pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci +processes and content including: * website content * tools that track contributors and keep the website up to date @@ -21,11 +9,3 @@ pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci proc This section of the guidebook discusses our GitHub organization, and processes for adding and managing content and infrastructure across the organization. - - -:::{toctree} -:glob: -:maxdepth: 2 - -* -::: diff --git a/community/github/issues.md b/community/github/issues.md index afa729b..3853b4c 100644 --- a/community/github/issues.md +++ b/community/github/issues.md @@ -1,82 +1,97 @@ # pyOpenSci GitHub issue process -When possible, pull requests, issue submissions and reviews should follow -standard open source workflows. Below are guidelines for handling issues. +When possible, GitHub pull requests, issue submissions, and reviews should follow +standard open source workflows. Below are guidelines for handling issues in the +pyOpenSci GitHub organization. -## Guidelines for New Issues +## Guidelines for new issues - -**Issues should be as specific as possible:** specifics within an issue help both our future selves and also outside contributors understand the goal or -desired outcome associated with addressing the issue. This is important both internally and for issues that we tag as `help-wanted`, which we hope community members will address in pyOpenSci sprints. +**Issues should be as specific as possible:** Specificity within an issue helps +both our future selves and outside contributors understand the goal or desired +outcome associated with addressing the issue. This is important both internally +and for issues tagged as `help-wanted`, which we hope community members will +address in pyOpenSci sprints. To ensure an issue is well-written and specific, include the following details: -- **Clear Title:** A concise and descriptive title summarizing the issue or feature request helps us scan through issues and understand what each issue is about. Below are some example titles that are specific +- **Clear title:** A concise and descriptive title summarizing the issue or + feature request helps us scan through issues and understand what each issue is + about. Below are some example titles that are specific: - * `Bug: broken link in link-to-page-here / name of page / document etc` - * `Fix: confusing paragraph on Python packaging with Hatch` - * `Add: page on using pixi for dependencies` + - `Bug: broken link in link-to-page-here / name of page / document etc` + - `Fix: confusing paragraph on Python packaging with Hatch` + - `Add: page on using pixi for dependencies` -- **Description:** A detailed explanation of the issue or feature request, including context, background information, and the reason for the request. Explain why the issue is important and what problem it solves. +- **Description:** A detailed explanation of the issue or feature request, + including context, background information, and the reason for the request. + Explain why the issue is important and what problem it solves. -- **Screenshots/Code Samples:** Include screenshots, code snippets, links, or any other relevant files that can help others in understanding the issue better. +- **Screenshots/code samples:** Include screenshots, code snippets, links, or + any other relevant files that can help others in understanding the issue + better. -- **Possible Solutions/Recommendations:** It's helpful to provide any ideas or suggestions for how to address the issue, which can help guide contributors towards a solution. +- **Possible solutions/recommendations:** It's helpful to provide any ideas or + suggestions for how to address the issue, which can help guide contributors + towards a solution. -- **Related Issues or Pull Requests:** Add references to any related issues or pull requests, which provides additional context and understanding of the broader scope of the issue. +- **Related issues or pull requests:** Add references to any related issues or + pull requests, which provides additional context and understanding of the + broader scope of the issue. ### If you are reporting a code bug -* **Steps to Reproduce (for bugs):** A step-by-step guide (generally a list or narrative) on how to reproduce the issue, including relevant code snippets, commands, or configurations. +- **Steps to reproduce (for bugs):** A step-by-step guide (generally a list or + narrative) on how to reproduce the issue, including relevant code snippets, + commands, or configurations. -* **Expected vs. Actual Behavior (for bugs):** A description of what you expected to happen and what actually happened. This helps in understanding the discrepancy and the impact of the bug. +- **Expected vs. actual behavior (for bugs):** A description of what you + expected to happen and what actually happened. This helps in understanding + the discrepancy and the impact of the bug. -* **Environment Details (for bugs):** Details about the environment where the issue was observed, such as operating system, Python version, library versions, and any other relevant software/hardware details. +- **Environment details (for bugs):** Details about the environment where the + issue was observed, such as operating system, Python version, library + versions, and any other relevant software/hardware details. ### If you have permissions, label the issue -While outside contributors will not have permission to label issues, pyOpenSci core team members and volunteers will. Be sure to add appropriate labels to -issues to make it easier to triage them. +While outside contributors will not have permission to label issues, pyOpenSci +core team members and volunteers will. Be sure to add appropriate labels to +issues to make them easier to triage. ## Help-wanted / sprintable issues -If an issue is something that anyone in the community could potentially -address, it's ideal to label the issue with `help-wanted` and/or `sprintable`. -A sprintable issue refers to an issue that could be completed or worked on -during a 1-2 day sprint, thus it should be smaller and more confined in scope. -A help-wanted issue is one that anyone is welcome to work on during whatever -time they have available. +If an issue is something that anyone in the community could potentially address, +it's ideal to label the issue with `help-wanted` and/or `sprintable`. A +sprintable issue refers to an issue that could be completed or worked on during +a 1-2 day sprint, thus it should be smaller and more confined in scope. A +help-wanted issue is one that anyone is welcome to work on during whatever time +they have available. Once the `help-wanted` or `sprintable` issue label is added, the issue will be automatically added to our [pyOpenSci help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). -This automation is implemented currently for a single repository (the packaging guide), but we plan to implement it for other repositories using the add-to-project GitHub action. - +This automation is implemented currently for a single repository (the packaging +guide), but we plan to implement it for other repositories using the +add-to-project GitHub action. :::{note} The issue will be archived from the project board once it is closed. ::: - -:::{todo} -Add link to sprints page when it's online +:::{seealso} +[Learn more about pyOpenSci sprint events.](/community/events/sprints) ::: -If an issue is unclear, a pyOpenSci staff member or designated community -member can ask the issue author to provide more information. - - - - - +If an issue is unclear, a pyOpenSci staff member or designated community member +can ask the issue author to provide more information. :::{todo} -Add section on labels +Add section on labels once we have things synced up across repos. ::: -## Issue Maintenance +## Issue maintenance Our goal at pyOpenSci is to keep our list of issues current and active. -Quarterly issue cleanup sessions are implemented to ensure issues are -either being actively addressed, or to assess whether older or stale issues can +Quarterly issue cleanup sessions are implemented to ensure issues are either +being actively addressed or to assess whether older or stale issues can potentially be closed. diff --git a/community/index.md b/community/index.md index 7cd529d..bb092eb 100644 --- a/community/index.md +++ b/community/index.md @@ -1,6 +1,5 @@ # Organization Handbook - :::{toctree} :hidden: :caption: Social Media Section @@ -9,20 +8,19 @@ Social Media Slack ::: - :::{toctree} :hidden: -:caption: GitHub Section +:caption: GitHub Processes GitHub +Our Repos +GitHub Issue Guidelines ::: - :::{toctree} :hidden: :caption: pyOpenSci Events Events pyOpenSci Sprints - ::: From 64f51f72a5a557a859133cbcb985d7264d11cdf9 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 4 Jun 2024 14:35:10 -0600 Subject: [PATCH 47/52] Add: ci and pr's content --- community/github/continuous-integration.md | 8 +- community/github/our-repositories.md | 108 ++++++++++++--------- community/github/pull-requests.md | 25 ++--- 3 files changed, 80 insertions(+), 61 deletions(-) diff --git a/community/github/continuous-integration.md b/community/github/continuous-integration.md index 68a7e98..22049f7 100644 --- a/community/github/continuous-integration.md +++ b/community/github/continuous-integration.md @@ -22,7 +22,7 @@ free from errors or issues related to the specific checks that have passed. * **Red X's**: These indicate that the code has failed the associated CI checks. This means there are issues that need to be addressed before the code can be merged. The issues could be related to code style, formatting, tests, or other criteria specified by the CI configuration. -#### If a CI check is red: +#### If a CI check is red 1. **Click on "Details"** next to the failed check to get more information about the failure. 2. **Review the logs or output** provided to understand what went wrong. @@ -39,7 +39,6 @@ If you don't know who to ping, no worries. Someone from the pyOpenSci organizati Generally we require a single passing approval in order to merge a pull request. However, in some cases, if you are a pyOpenSci staff member or community member with admin / write access, it could be the case that you need to merge something immediately (i.e. fixing a small piece of breaking code, a spelling error, or adding a new piece of content that has already been agreed upon). ::: - ## CI and outside contributors If someone from outside of the pyOpenSci organization submits a pull request, then someone within the organization needs to approve and run CI. If you @@ -48,14 +47,15 @@ have those super powers, please go ahead and allow CI to run for new contributor Next to each CI step that was run, there is a details button. If you click on that link, it will give you more information about what has run / not run as expected in the build. ## Website CI checks + All of our website repositories have several CI builds including: 1. A link checker 2. `htmlproofer`, which checks both links and alt tags, as well as images 3. a CI build that shows you what the rendered site looks like when built online. Currently we are using [CircleCI](https://circleci.com/) for a live rendered build, as CircleCI allows for in-browser website build checks. GitHub requires you to download, unzip and view and archive with the build site locally. - (pre-commit-ci)= + ## About the Pre-Commit CI Bot The [Pre-commit CI bot](https://pre-commit.ci/) is a continuous integration service that automatically @@ -100,7 +100,7 @@ To setup the bot in a new repository: 1. **Enable pre-commit.ci** on your repository through the [pre-commit.ci website](https://pre-commit.ci/). -2. The bot will automatically run checks and apply fixes on pull requests. +2. The pre-commit.ci bot will automatically run checks and apply fixes on pull requests. 3. Review the bot's output and ensure all checks pass before merging your code. This approach ensures that all contributions meet our pyOpenSci code and diff --git a/community/github/our-repositories.md b/community/github/our-repositories.md index f11674b..23f3aa3 100644 --- a/community/github/our-repositories.md +++ b/community/github/our-repositories.md @@ -1,4 +1,4 @@ -# pyOpenSci GitHub Repositories +# pyOpenSci GitHub repositories :::{todo} Add repositories from the pyOpenSci organization. @@ -7,96 +7,114 @@ Add repositories from the pyOpenSci organization. pyOpenSci manages multiple GitHub repositories to support various community activities. Below is a description of each repository. -### [Software-review Repository](https://www.pyopensci.org/software-peer-review/) +### [Software-review repository](https://www.pyopensci.org/software-peer-review/) The software-review repository is where community package submissions are -peer-reviewed. All submissions are made through GitHub Issues. [Learn more about -our peer review process here.](https://www.pyopensci.org/software-peer-review/) +peer-reviewed. All submissions are made through GitHub Issues. [Learn more +about our peer review process here.](https://www.pyopensci.org/software-peer-review/) :::{important} Important: If a pyOpenSci core member identifies an issue with the review -submission template, consult both the editorial team and core team before making -any changes. This template's data are processed by a Python workflow, and even -small modifications could disrupt the language processing. +submission template, consult both the editorial team and core team before +making any changes. This template's data are processed by a Python workflow, +and even small modifications could disrupt the language processing. ::: -## Software-peer-review Guidebook Repository +## Software-peer-review guidebook repository -This repository hosts our [software peer review guidebook](https://www.pyopensci.org/software-peer-review/), -which documents the processes and guidelines for authors, editors, the Editor in -Chief, and the peer review triage team as they manage our open peer review process. It also details our peer review policies, -partnerships, and the templates used in the review process. +This repository hosts our [software peer review +guidebook](https://www.pyopensci.org/software-peer-review/), which documents +the processes and guidelines for authors, editors, the Editor in Chief, and the +peer review triage team as they manage our open peer review process. It also +details our peer review policies, partnerships, and the templates used in the +review process. -## Python-package-guide Repository +## Python-package-guide repository -The [python-package-guide repository](https://www.pyopensci.org/python-package-guide/) -contains our community-developed guidelines and tutorials on Python packaging. -These resources are beginner-friendly and reflect Python packaging best practices. +The [python-package-guide +repository](https://www.pyopensci.org/python-package-guide/) contains our +community-developed guidelines and tutorials on Python packaging. These +resources are beginner-friendly and reflect Python packaging best practices. -## [pyosMeta Repository](https://github.com/pyOpenSci/pyosMeta) +## [pyosMeta repository](https://github.com/pyOpenSci/pyosMeta) -The pyosMeta repository contains a Python package published on PyPI that we use to track our -package review and contributor data. This data is used in a GitHub action to -update our website. +The pyosMeta repository contains a Python package published on PyPI that we use +to track our package review and contributor data. This data is used in a GitHub +action to update our website. :::{todo} Add more information about the contributor data workflow ... ::: -## [pyopensci.github.io Repository](https://github.com/pyOpenSci/pyopensci.github.io) +## [pyopensci.github.io repository](https://github.com/pyOpenSci/pyopensci.github.io) -This repository contains code and content that builds and publishes our pyOpenSci website. The website, [pyOpenSci](https://www.pyopensci.org/), is hosted on GitHub and -uses the [Jekyll Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/) theme. The Python packages page, contributor page and peer review team page are all updated automagically using a -GitHub action workflow that is supported by the pyosMeta Python package discussed above. The workflow runs every other week but can be triggered manually as a **workflow -dispatch**. +This repository contains code and content that builds and publishes our +pyOpenSci website. The website, [pyOpenSci](https://www.pyopensci.org/), is +hosted on GitHub and uses the [Jekyll Minimal +Mistakes](https://mmistakes.github.io/minimal-mistakes/) theme. The Python +packages page, contributor page, and peer review team page are all updated +automatically using a GitHub action workflow that is supported by the pyosMeta +Python package discussed above. The workflow runs every other week but can be +triggered manually as a **workflow dispatch**. ### Critical CI workflows in this repository -The [contributor workflow action](https://github.com/pyOpenSci/pyopensci.github.io/blob/main/.github/workflows/update-contribs-reviews.yml) is a custom GitHub -action that is used to update the following website pages: +The [contributor workflow +action](https://github.com/pyOpenSci/pyopensci.github.io/blob/main/.github/workflows/update-contribs-reviews.yml) +is a custom GitHub action that is used to update the following website pages: * contributor page * package listing page -* editorial, advisory council and executive council listing +* editorial, advisory council, and executive council listing -It runs as a cron job every other week but also can be run manually as a workflow -dispatch. If you need to update our package listing or contributor list on -the fly, please run this action. +It runs as a cron job every other week but also can be run manually as a +workflow dispatch. If you need to update our package listing or contributor +list on the fly, please run this action. The action will: -1. parse through all of our accepted pyOpenSci packages -2. collect package names, authors, reviewers and editors -3. collect metadata for the packages authors reviewers and editors using the GitHub (REST) API +1. Parse through all of our accepted pyOpenSci packages. +2. Collect package names, authors, reviewers, and editors. +3. Collect metadata for the package authors, reviewers, and editors using the + GitHub (REST) API. 4. Create 2 output YAML files discussed below. -The YAML output files and then used to populate content on the website. +The YAML output files are then used to populate content on the website. ### Metadata stored in this repository -1. **Packages.yml**: Updates the [Python Packages page](https://www.pyopensci.org/python-packages.html) - by parsing reviews from software-review repository issues. -2. **Contributors.yml**: Updates the [Our Community page](https://www.pyopensci.org/our-community/index.html) - by parsing data from all organization repositories. +1. **Packages.yml**: Updates the [Python Packages + page](https://www.pyopensci.org/python-packages.html) by parsing reviews + from software-review repository issues. +2. **Contributors.yml**: Updates the [Our Community + page](https://www.pyopensci.org/our-community/index.html) by parsing data + from all organization repositories. :::{todo} Update the website contributors guide with general CI and specific Jekyll information. ::: -## [pyOpenSci Sphinx Theme](https://github.com/pyOpenSci/pyos-sphinx-theme) +## [pyOpenSci Sphinx theme](https://github.com/pyOpenSci/pyos-sphinx-theme) **Platform:** Sphinx book template that builds on top of the pydata_sphinx_theme -All of our pyOpenSci Sphinx books (handbook, packaging guide, software review guide ) have been customized to match our pyOpenSci branding. This repo contains the start of a Sphinx theme that will incorporate all of our branding, so we do not have to manually apply the branding and update it individually in each repo. Instead, we can update branding in the theme and it will be applied across all of our repositories that use the theme. +All of our pyOpenSci Sphinx books (handbook, packaging guide, software review +guide) have been customized to match our pyOpenSci branding. This repo contains +the start of a Sphinx theme that will incorporate all of our branding, so we do +not have to manually apply the branding and update it individually in each repo. +Instead, we can update branding in the theme, and it will be applied across all +of our repositories that use the theme. -Creating a theme was inspired by [Chris Holdgraf's](https://chrisholdgraf.com/) 2i2c Sphinx theme. +Creating a theme was inspired by the +[2i2c Sphinx theme](https://sphinx-2i2c-theme.readthedocs.io/en/latest/). -## [Handbook Repository](https://github.com/pyOpenSci/handbook) +## [Handbook repository](https://github.com/pyOpenSci/handbook) -**Platform:** Sphinx book running the pydata_sphinx_theme +**Platform:** Sphinx book running the `pydata_sphinx_theme` -This is where we store our organization governance, code of conduct and processes around how we operate as an organization. +This is where we store our organization governance, code of conduct, and +processes around how we operate as an organization. ## [pyosPackage repository](https://github.com/pyOpenSci/pyosPackage) diff --git a/community/github/pull-requests.md b/community/github/pull-requests.md index 298e3de..9020161 100644 --- a/community/github/pull-requests.md +++ b/community/github/pull-requests.md @@ -9,7 +9,7 @@ New pull requests should: * be created from a fork rather than the pyOpenSci owned parent repository. * never be submitted from the `main` branch of your fork. -Authors of new pull requests should, whenever possible, do their best to create clean pull requests. +Authors of new pull requests should, whenever possible, do their best to create clean pull requests. A clean pull request: @@ -21,9 +21,9 @@ A clean pull request: Review your own pull request before asking someone else to review it for you. You might be surprised that you notice things in the pull request that you didn't notice when working on the content locally. ::: -### Pull request content +### Pull request content -Below are some guidelines for pull request content. Clean pull requests lead to simpler reviews & faster merging! +Below are some guidelines for pull request content. Clean pull requests lead to simpler reviews & faster merging! 1. **Keep It Small**: Aim for one logical change per pull request to simplify review. 1. **Create a descriptive PR Title and Summary**: Clearly state what the PR achieves and why, including any related issue numbers or discussions. @@ -39,8 +39,9 @@ Below are some guidelines for pull request content. Clean pull requests lead to 1. **Keep your branch updated**: Regularly rebase your fork from the main branch (if possible) to avoid / clean up any merge conflicts and to keep your PR up to date. :::{info} + * [tips for better pull requests](https://opensource.com/article/18/6/anatomy-perfect-pull-request) -* pyOpenSci has also enabled an "update branch" feature in the pull request, which will update your branch to be in sync with main. In most cases, this creates a merge commit rather than a rebase. +* pyOpenSci has also enabled an "update branch" feature in the pull request, which will update your branch to be in sync with main. In most cases, this creates a merge commit rather than a rebase. ::: ### Regular vs New Contributors @@ -68,7 +69,6 @@ The above process is often implemented on a case-by-case basis depending on the :::{todo} Did we address these questions above?? - What are the expectations for an external contributor? What should they have done locally? Do we expect someone to have done all the wrangling with Ruby and Jekyll? @@ -102,14 +102,14 @@ specified style and format rules before it gets committed to the repository. We generally use the following hooks: * **Autoformat**: Makes sure files end in a newline and only a newline. - - `end-of-file-fixer` + * `end-of-file-fixer` * **Lint**: Check for files with names that would conflict on a case-insensitive filesystem like MacOS HFS+ or Windows FAT. - - `check-case-conflict` + * `check-case-conflict` * **Whitespace**: Clean up trailing white space at the end of individual lines. - - `trailing-whitespace` + * `trailing-whitespace` * **Spelling**: Check for spelling issues within the repository. - - `codespell` + * `codespell` Setting up pre-commit locally is optional because we have the pre-commit bot setup in our CI workflows. However, if you are a pyOpenSci staff member regularly contributes, we suggest that you set it up locally in our repos to ensure @@ -124,17 +124,18 @@ To set up pre-commit locally, follow these steps: ```bash pip install pre-commit ``` + 2. From the root of the pyOpenSci repository that you wish to run pre-commit hooks on, run ```bash pre-commit install ``` + This will install all of the hooks that pyOpenSci has setup for that repository. Most often there is a spell checker, and several markdown file formatters, which will remove excess white space. - 3. To run pre-commit on all files in the repository - ```bash @@ -174,6 +175,7 @@ contributors across all of our GitHub repositories. Contributor information is then published on [our website](https://www.pyopensci.org/our-community/index.html#pyopensci-community-contributors). ### Who we acknowledge + pyOpenSci is liberal in acknowledging all contributions, regardless of their size. When someone new submits an issue or PR, add them as a contributor to the repo using the bot. @@ -193,18 +195,17 @@ When you add a user, the bot will open a pull request that can be squashed and merged. Once merged, their profile image and name will appear in the README file of that repository. - pyOpenSci then has an automated build that will parse contributors across all of our repos, adding them to the contributor list and noting the type(s) of contributions that they have made (e.g., packaging guide, peer review guide). :::{todo} + ## GitHub & CI * CI (Continuous integration) will be run on each new commit added to all of our public repositories (that have content). - ### Permissions to run CI In general, things are setup so CI doesn’t run automagically for new contributors. Rather, someone with triage rights will need to approve the workflow to run by hitting the approve and run button that will appear (see image below). We have things set up this way to avoid spam PRs and commits that will abuse our CI use. We could potentially adjust in the future, but also can adjust by allowing more people with “access levels” that can approve CI. From 6bdb2ef7153a9302b85003a1ce89489987b9b4ae Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 13 Aug 2024 14:30:46 -0600 Subject: [PATCH 48/52] Fix: edits from reviews --- community/github/continuous-integration.md | 131 +++++++++----- community/github/pull-requests.md | 199 ++++++++++++++------- 2 files changed, 215 insertions(+), 115 deletions(-) diff --git a/community/github/continuous-integration.md b/community/github/continuous-integration.md index 22049f7..6969ab0 100644 --- a/community/github/continuous-integration.md +++ b/community/github/continuous-integration.md @@ -2,82 +2,119 @@ ## What is CI? -Continuous Integration (CI) refers to checks and tests that are triggered by events that occur on GitHub such as commit pushes, pull requests and even merges to a GitHub repository. In the pyOpenSci organization, each commit -triggers at least one or more automated CI workflows. For the [pyOpenSci website repository](https://www.pyopensci.org/) and our online books such as the [Python packaging guidebook that is written using Sphinx](https://github.com/pyopensci/python-package-guide), this build will: - -* build the live rendered version of the online content with any changes added in the current commit(s) or pull requests. -* check the text for spelling issues, check images for missing alt tags and more. +Continuous Integration (CI) refers to checks and tests that are triggered by +events that occur on GitHub such as commit pushes, pull requests, and even +merges to a GitHub repository. In the pyOpenSci organization, each commit +triggers at least one or more automated CI workflows. For the [pyOpenSci +website repository](https://www.pyopensci.org/) and our online books such as +the [Python packaging guidebook that is written using +Sphinx](https://github.com/pyopensci/python-package-guide), this build will: + +* Build the live rendered version of the online content with any changes added + in the current commit(s) or pull requests. +* Check the text for spelling issues, check images for missing alt tags, and + more. If the repository has code, it will check for code style. -Having a CI setup on each pyOpenSci GitHub repository ensures that we detect issues such as bad links or broken code before they're merged into the main repository. +Having a CI setup on each pyOpenSci GitHub repository ensures that we detect +issues such as bad links or broken code before they're merged into the main +repository. ### What do the green and red checks mean? The green and red checks in the CI block indicate the status of these automated checks: -* **Green Checks**: These indicate that the code has passed the CI checks. This means the code meets the project's standards and is likely -free from errors or issues related to the specific checks that have passed. - -* **Red X's**: These indicate that the code has failed the associated CI checks. This means there are issues that need to be addressed before the code can be merged. The issues could be related to code style, formatting, tests, or other criteria specified by the CI configuration. +* **Green checks**: These indicate that the code has passed the CI checks. + This means the code meets the project's standards and is likely free from + errors or issues related to the specific checks that have passed. +* **Red X's**: These indicate that the code has failed the associated CI + checks. This means there are issues that need to be addressed before the code + can be merged. The issues could be related to code style, formatting, tests, + or other criteria specified by the CI configuration. #### If a CI check is red -1. **Click on "Details"** next to the failed check to get more information about the failure. +1. **Click on "Details"** next to the failed check to get more information + about the failure. 2. **Review the logs or output** provided to understand what went wrong. 3. **Make the necessary changes** to fix the issue. -4. **Push the updated code** to the pull request to trigger the CI checks again. +4. **Push the updated code** to the pull request to trigger the CI checks + again. -If something isn't working as expected or you are having a hard time understanding why CI is failing (we've all been there!), please ping someone else in the organization for help. As a pyOpenSci community, we are always here to help each other. +If something isn't working as expected or you are having a hard time +understanding why CI is failing (we've all been there!), please ping someone +else in the organization for help. As a pyOpenSci community, we are always +here to help each other. -If all CI checks are green, you are good to go. Ping a pyOpenSci repository owner on GitHub to review your pull request. The pull request can be merged once you have approval from another repository owner. +If all CI checks are green, you are good to go. Ping a pyOpenSci repository +owner on GitHub to review your pull request. The pull request can be merged +once you have approval from another repository owner. -If you don't know who to ping, no worries. Someone from the pyOpenSci organization will see your pull request and get back to you. +If you don't know who to ping, no worries. Someone from the pyOpenSci +organization will see your pull request and get back to you. :::{note} -Generally we require a single passing approval in order to merge a pull request. However, in some cases, if you are a pyOpenSci staff member or community member with admin / write access, it could be the case that you need to merge something immediately (i.e. fixing a small piece of breaking code, a spelling error, or adding a new piece of content that has already been agreed upon). +Generally, we require a single passing approval to merge a pull request. +However, in some cases, if you are a pyOpenSci staff member or community +member with admin/write access, it could be the case that you need to merge +something immediately (i.e., fixing a small piece of breaking code, a spelling +error, or adding a new piece of content that has already been agreed upon). ::: ## CI and outside contributors -If someone from outside of the pyOpenSci organization submits a pull request, then someone within the organization needs to approve and run CI. If you -have those super powers, please go ahead and allow CI to run for new contributors. You can’t break anything by running CI, so always feel confident in our repos when you click that button, assuming that the PR is legitimate and submitted from a valid user! +If someone from outside of the pyOpenSci organization submits a pull request, +then someone within the organization needs to approve and run CI. If you have +those superpowers, please go ahead and allow CI to run for new contributors. +You can’t break anything by running CI, so always feel confident in our repos +when you click that button, assuming that the PR is legitimate and submitted +from a valid user! -Next to each CI step that was run, there is a details button. If you click on that link, it will give you more information about what has run / not run as expected in the build. +Next to each CI step that was run, there is a details button. If you click on +that link, it will give you more information about what has run/not run as +expected in the build. ## Website CI checks -All of our website repositories have several CI builds including: +All of our website repositories have several CI builds, including: -1. A link checker -2. `htmlproofer`, which checks both links and alt tags, as well as images -3. a CI build that shows you what the rendered site looks like when built online. Currently we are using [CircleCI](https://circleci.com/) for a live rendered build, as CircleCI allows for in-browser website build checks. GitHub requires you to download, unzip and view and archive with the build site locally. +1. A link checker. +2. `htmlproofer`, which checks both links and alt tags, as well as images. +3. A CI build that shows you what the rendered site looks like when built + online. Currently, we are using [CircleCI](https://circleci.com/) for a + live rendered build, as CircleCI allows for in-browser website build checks. + GitHub requires you to download, unzip, and view an archive with the build + site locally. (pre-commit-ci)= - ## About the Pre-Commit CI Bot -The [Pre-commit CI bot](https://pre-commit.ci/) is a continuous integration service that automatically -runs pre-commit hooks on each pull request. This helps maintain code quality -and consistency without requiring developers to run pre-commit locally. +The [Pre-commit CI bot](https://pre-commit.ci/) is a continuous integration +service that automatically runs pre-commit hooks on each pull request. This +helps maintain code quality and consistency without requiring developers to +run pre-commit locally. To run the bot on a PR, add the following command to a standalone comment: `pre-commit autofix` -When you do this, the bot will run all of the hooks that it can, adding -a new commit to the pull request for you. +When you do this, the bot will run all of the hooks that it can, adding a new +commit to the pull request for you. -#### What the Bot Can Fix +### What the bot can fix -The bot can in-place fix many linting and style issues in our content, including: +The bot can in-place fix many linting and style issues in our content, +including: -* Automatically fixing formatting issues such as trailing whitespace and missing - newlines. -* Apply code style adjustments as specified by hooks like [`black`](https://github.com/psf/black) and [`isort`](https://pycqa.github.io/isort/). +* Automatically fixing formatting issues such as trailing whitespace and + missing newlines. +* Applying code style adjustments as specified by hooks like + [`black`](https://github.com/psf/black) and + [`isort`](https://pycqa.github.io/isort/). -#### What the Bot Can’t Fix +### What the bot can’t fix The bot can't fix some things, such as: @@ -86,23 +123,25 @@ The bot can't fix some things, such as: conflicts or making design decisions. * Spelling errors. -In the case that the bot finds errors that it can't fix, you will need to -make those changes locally. +If the bot finds errors that it can't fix, you will need to make those changes +locally. -### Using the Bot Instead +### Using the bot instead of pre-commit hooks -pyOpenSci contributors may prefer not to set up pre-commit locally. In that case, -we can rely on the pre-commit.ci bot to fix things as needed. +pyOpenSci contributors may prefer not to set up pre-commit locally. In that +case, we can rely on the pre-commit.ci bot to fix things as needed. -#### Bot setup +### Bot setup -To setup the bot in a new repository: +To set up the bot in a new repository: 1. **Enable pre-commit.ci** on your repository through the [pre-commit.ci website](https://pre-commit.ci/). -2. The pre-commit.ci bot will automatically run checks and apply fixes on pull requests. -3. Review the bot's output and ensure all checks pass before merging your code. +2. The pre-commit.ci bot will automatically run checks and apply fixes on + pull requests. +3. Review the bot's output and ensure all checks pass before merging your + code. -This approach ensures that all contributions meet our pyOpenSci code and -text quality standards without requiring each contributor to install and run +This approach ensures that all contributions meet our pyOpenSci code and text +quality standards without requiring each contributor to install and run pre-commit locally. diff --git a/community/github/pull-requests.md b/community/github/pull-requests.md index 9020161..1777601 100644 --- a/community/github/pull-requests.md +++ b/community/github/pull-requests.md @@ -1,70 +1,115 @@ -# 2. pyOpenSci pull request process +# 2. pyOpenSci Pull Request Process -When possible, pull request and issue submissions and reviews should follow standard open source workflows. Below are guidelines for pull requests. +When possible, pull request and issue submissions and reviews should follow +standard open-source workflows. Below are guidelines for pull requests. ## Pull Requests New pull requests should: -* be created from a fork rather than the pyOpenSci owned parent repository. -* never be submitted from the `main` branch of your fork. +* Be created from a fork rather than the pyOpenSci-owned parent repository. +* Never be submitted from the `main` branch of your fork. -Authors of new pull requests should, whenever possible, do their best to create clean pull requests. +Authors of new pull requests should, whenever possible, do their best to +create clean pull requests. A clean pull request: -* is focused, and easy to review, -* can be more quickly reviewed (and in turn merged), saving everyone time, and -* closes an existing issue (with the exception of new content such as blog posts, which we manage internally using Asana) +* Is focused on fixing or adding a single thing or a single related set of + things. +* Is easy to review, meaning it doesn't have too many files and too much + new content. +* Can be more quickly reviewed (and in turn merged), saving everyone time. +* Closes an existing issue (with the exception of new content such as blog + posts, which we manage internally using Asana). :::{tip} -Review your own pull request before asking someone else to review it for you. You might be surprised that you notice things in the pull request that you didn't notice when working on the content locally. +Review your own pull request before asking someone else to review it for you. +You might be surprised that you notice things in the pull request that you +didn't notice when working on the content locally. ::: -### Pull request content - -Below are some guidelines for pull request content. Clean pull requests lead to simpler reviews & faster merging! - -1. **Keep It Small**: Aim for one logical change per pull request to simplify review. -1. **Create a descriptive PR Title and Summary**: Clearly state what the PR achieves and why, including any related issue numbers or discussions. -1. **Double check that the files committed to the pull request clearly align with the suggested changes being made in the pull request**. For example, if a new guidebook page contains images, all images that are new to the guidebook should be included in the list of files in the pr. If the new page reuses images, then link to the existing images in the repository rather than re-adding them. -1. **Follow coding / style guide and other organization standards (if applicable)**: Stick to the project's coding guidelines for style and organization, if they exist. This is more often relevant to code pull requests than text. -1. **Review Your Own Pull request first**: Look over your PR critically before requesting reviews, in order to catch any mistakes early. -1. **Respond Respectfully**: Be open to feedback and discuss suggestions to improve the project. -1. **Check CI for any red X's (more on CI below)**: If your pull request returns a red X in the "checks/CI" section, then it's worth seeing if you can figure out what is broken in the build. If you aren't sure, no problem. Leave a note for the reviewer to allow them to help you understand what needs to be fixed (if anything). +### Pull Request Content + +Below are some guidelines for pull request content. Clean pull requests +lead to simpler reviews and faster merging! + +1. **Keep It Small**: Aim for one logical change per pull request to + simplify review. +2. **Create a Descriptive PR Title and Summary**: Clearly state what the + PR achieves and why, including any related issue numbers or discussions. +3. **Double-Check Files**: Ensure the files committed clearly align with + the changes in the pull request. For example, if a new guidebook page + contains images, all new images should be included in the PR. Reuse + existing images by linking to them rather than re-adding them. +4. **Follow Coding/Style Guidelines**: Stick to the project's coding and + style guidelines, if applicable. This is more relevant to code PRs + than text. +5. **Review Your Own PR First**: Look over your PR critically before + requesting reviews to catch mistakes early. +6. **Respond Respectfully**: Be open to feedback and discuss suggestions + to improve the project. +7. **Check CI for Any Red X's**: If your pull request returns a red X in + the "checks/CI" section, try to figure out what is broken in the build. + If you're unsure, leave a note for the reviewer to help understand what + needs fixing. ### Highly Recommended -1. **Create clear commit messages**: Explain why changes are made, not just what was changed. -1. **Keep your branch updated**: Regularly rebase your fork from the main branch (if possible) to avoid / clean up any merge conflicts and to keep your PR up to date. +1. **Create Clear Commit Messages**: Explain why changes are made, not + just what was changed. +2. **Keep Your Branch Updated**: Regularly rebase your fork from the main + branch (if possible) to avoid/clean up merge conflicts and keep your PR + up to date. :::{info} -* [tips for better pull requests](https://opensource.com/article/18/6/anatomy-perfect-pull-request) -* pyOpenSci has also enabled an "update branch" feature in the pull request, which will update your branch to be in sync with main. In most cases, this creates a merge commit rather than a rebase. +* [Tips for Better Pull Requests](https://opensource.com/article/18/6/anatomy-perfect-pull-request) +* pyOpenSci has also enabled an "update branch" feature in the pull request, + which will update your branch to be in sync with main. In most cases, + this creates a merge commit rather than a rebase. ::: -### Regular vs New Contributors +### Regular vs. New Contributors -There is no right or wrong when it comes to building a website repository locally. pyOpenSci staff and other community members who contribute to pyOpenSci regularly will often opt to build online -resources locally for live interactive development and edits. Building locally -is an ideal way for internal contributors to double check website updates before pushing to GitHub and looking at GitHub action updates. +There is no right or wrong when it comes to building a website repository +locally. pyOpenSci staff and regular contributors often opt to build +resources locally for live interactive development and edits. Building +locally is an ideal way for internal contributors to double-check website +updates before pushing to GitHub and checking GitHub action updates. -Contributors making less-regular contributions, or those submitting quick fixes to pages on our website, might opt to use our continuous integration (CI) checks as a way to double check the website build and also to check for broken and bad links, missing alt tags and more within a pull request. +Contributors making less-regular contributions, or those submitting quick +fixes to website pages, might opt to use our continuous integration (CI) +checks as a way to double-check the website build and also to check for +broken links, missing alt tags, and more within a pull request. A large volume of the content in our GitHub repositories is text-based documentation and tutorials. For text-based repositories, such as our -website, packaging guide and peer review guide, we have CI platforms set up that allow a contributor to submit a pull request with a change, without needing to build the site locally. - -### Supporting new contributors - -pyOpenSci strives to support new and existing contributors in enhancing our online resources. As such, we will support new contributors in this process. When a new pull request is submitted by someone, we will do the following: - -* Evaluate the contributors background, where possible. If this is their first pull request submitted through a sprint, then we'll support them in their efforts by pointing out CI and providing specific line-by-line feedback. -* If fixes to the existing pr are straight forward, the reviewer can "suggest inline changes" on the pull request by highlighting one or more modified lines, and suggesting edits in place. This approach of inline suggestions is often a quick way to integrate feedback from a review. -* If fixes to the existing PR are more involved, clearly articulate what is wrong in the pull request and ask the contributor if they feel comfortable addressing it. If they don't, then someone in the core pyOpenSci team can support them in getting their pull request edited, reviewed and merged. - -The above process is often implemented on a case-by-case basis depending on the contributor's background. +website, packaging guide, and peer review guide, we have CI platforms set +up that allow a contributor to submit a pull request with a change, without +needing to build the site locally. + +### Supporting New Contributors + +pyOpenSci strives to support new and existing contributors in enhancing our +online resources. We will support new contributors in this process. When a +new pull request is submitted by someone, we will do the following: + +* Evaluate the contributor's background, where possible. If this is their + first pull request submitted through a sprint, then we'll support them + by pointing out CI and providing specific line-by-line feedback. +* If fixes to the existing PR are straightforward, the reviewer can + "suggest inline changes" on the pull request by highlighting one or more + modified lines and suggesting edits in place. This approach is often a + quick way to integrate feedback from a review. +* If fixes to the existing PR are more involved, clearly articulate what is + wrong in the pull request and ask the contributor if they feel comfortable + addressing it. If they don't, then someone from the core pyOpenSci team + can support them in getting their pull request edited, reviewed, and + merged. + +The above process is often implemented on a case-by-case basis depending on +the contributor's background. :::{todo} Did we address these questions above?? @@ -74,9 +119,11 @@ What should they have done locally? Do we expect someone to have done all the wrangling with Ruby and Jekyll? ::: -## Pull requests and Continuous Integration +## Pull Requests and Continuous Integration -At the bottom of every pull request is the Continuous Integration (CI) block. This block contains a set of checks that pyOpenSci has set up. Each check will have a red X or green check next to it. +At the bottom of every pull request is the Continuous Integration (CI) block. +This block contains a set of checks that pyOpenSci has set up. Each check +will have a red X or green check next to it. ## Pre-commit hooks and pre-commit.ci bot @@ -112,8 +159,10 @@ We generally use the following hooks: * `codespell` Setting up pre-commit locally is optional because we have the pre-commit bot -setup in our CI workflows. However, if you are a pyOpenSci staff member regularly contributes, we suggest that you set it up locally in our repos to ensure -spell check errors (that the pre-commit CI bot cannot fix in a PR) are addressed. +setup in our CI workflows. However, if you are a pyOpenSci staff member +regularly contributes, we suggest that you set it up locally in our repos to +ensure spell check errors (that the pre-commit CI bot cannot fix in a PR) are +addressed. ### Setting Up Pre-commit Locally @@ -157,56 +206,68 @@ use: git commit "commit message here" --no-verify ``` -### About the pre-commit CI Bot +### About the pre-commit CI bot -The [Pre-commit CI](https://pre-commit.ci/) bot is a continuous integration service that automatically -runs pre-commit hooks on each pull request. It also allows you to call the bot -to fix any issues with the pull request (with the exception of misspelled words). +The [Pre-commit CI](https://pre-commit.ci/) bot is a continuous integration +service that automatically runs pre-commit hooks on each pull request. It +also allows you to call the bot to fix any issues with the pull request +(with the exception of misspelled words). -This helps maintain code quality -and consistency without requiring contributors to run pre-commit locally. +This helps maintain code quality and consistency without requiring +contributors to run pre-commit locally. -[Learn more about pre-commit ci in our CI section here](pre-commit-ci) +[Learn more about pre-commit CI in our CI section here](pre-commit-ci). -### Acknowledging New Contributors +### Acknowledging new contributors -We use the [All-contributors bot](https://allcontributors.org/) to acknowledge -contributors across all of our GitHub repositories. Contributor information -is then published on [our website](https://www.pyopensci.org/our-community/index.html#pyopensci-community-contributors). +We use the [All-contributors bot](https://allcontributors.org/) to +acknowledge contributors across all of our GitHub repositories. Contributor +information is then published on +[our website](https://www.pyopensci.org/our-community/index.html#pyopensci-community-contributors). ### Who we acknowledge -pyOpenSci is liberal in acknowledging all contributions, regardless of their size. When -someone new submits an issue or PR, add them as a contributor to the repo using -the bot. +pyOpenSci is liberal in acknowledging all contributions, regardless of +their size. When someone new submits an issue or PR, add them as a +contributor to the repo using the bot. -* It is ok if their name is already on our website as a contributor, -if this is their first contribution to a different repo, or a different type of contribution, add them. We will acknowledge the different types of contributions that our wonderful volunteers make. -* If they are already added as a contributor to the repo where the pull request is, that is ok too. The bot will inform you! +* It is okay if their name is already on our website as a contributor. If + this is their first contribution to a different repo or a different type + of contribution, add them. We will acknowledge the different types of + contributions that our wonderful volunteers make. +* If they are already added as a contributor to the repo where the pull + request is, that is okay too. The bot will inform you! To add a contributor, at the bottom of a pull request or an issue, call the following command: -`@all-contributors please add @kiersi for code, review` + `@all-contributors please add @kiersi for code, review` -replaceing `@kiersi` with `@contributors-username`. + Replace `@kiersi` with `@contributors-username`. When you add a user, the bot will open a pull request that can be squashed and merged. Once merged, their profile image and name will appear in the README file of that repository. -pyOpenSci then has an automated build that will parse contributors across all of -our repos, adding them to -the contributor list and noting the type(s) of contributions that they have made -(e.g., packaging guide, peer review guide). +pyOpenSci then has an automated build that will parse contributors across +all of our repos, adding them to the contributor list and noting the type(s) +of contributions that they have made (e.g., packaging guide, peer review +guide). :::{todo} ## GitHub & CI -* CI (Continuous integration) will be run on each new commit added to all of our public repositories (that have content). +* CI (Continuous Integration) will be run on each new commit added to all + of our public repositories (that have content). ### Permissions to run CI -In general, things are setup so CI doesn’t run automagically for new contributors. Rather, someone with triage rights will need to approve the workflow to run by hitting the approve and run button that will appear (see image below). We have things set up this way to avoid spam PRs and commits that will abuse our CI use. We could potentially adjust in the future, but also can adjust by allowing more people with “access levels” that can approve CI. +In general, things are set up so CI doesn’t run automatically for new +contributors. Instead, someone with triage rights will need to approve the +workflow to run by hitting the "approve and run" button that will appear +(see image below). We have set things up this way to avoid spam PRs and +commits that might abuse our CI use. We could potentially adjust this in +the future, but we can also adjust by allowing more people with access +levels that can approve CI. ::: From f31a9032a3d3369d74accd223f1647d1f98f6746 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 13 Aug 2024 14:40:32 -0600 Subject: [PATCH 49/52] Fix: toctree --- community/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/community/index.md b/community/index.md index bb092eb..f390cba 100644 --- a/community/index.md +++ b/community/index.md @@ -15,6 +15,8 @@ Slack GitHub Our Repos GitHub Issue Guidelines +Pull Requests +Continuous Integration (CI) ::: :::{toctree} From f61e86608fea84dc3eddbe1e3b7e920c3648dc59 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 1 Jul 2024 17:43:07 +0000 Subject: [PATCH 50/52] [pre-commit.ci] pre-commit autoupdate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit updates: - [github.com/pre-commit/pre-commit-hooks: v4.5.0 → v4.6.0](https://github.com/pre-commit/pre-commit-hooks/compare/v4.5.0...v4.6.0) - [github.com/codespell-project/codespell: v2.2.6 → v2.3.0](https://github.com/codespell-project/codespell/compare/v2.2.6...v2.3.0) --- .pre-commit-config.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e126d31..5d3cbb5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -23,7 +23,7 @@ repos: # Misc commit checks - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: v4.6.0 # ref: https://github.com/pre-commit/pre-commit-hooks#hooks-available hooks: # Autoformat: Makes sure files end in a newline and only a newline. @@ -34,6 +34,6 @@ repos: - id: trailing-whitespace - repo: https://github.com/codespell-project/codespell - rev: v2.2.6 + rev: v2.3.0 hooks: - id: codespell From 9ef28a568aaf34a296e79b4735885fa124b692b4 Mon Sep 17 00:00:00 2001 From: Jesse Mostipak Date: Tue, 20 Aug 2024 17:39:47 -0500 Subject: [PATCH 51/52] feat: Add section on internal document storage -- google drive (#76) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update README.md clarified governance to be governance handbook, and corrected the link to point to the new handbook URL (was pointing to /governance) * added note on internal documentation * updated corresponding index entry * '[pre-commit.ci 🤖] Apply code format tools to PR' * fix: active voice and clarification of needs for shared storage --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Leah Wasser --- organization/index.md | 7 +++++++ organization/internal-documentation.md | 13 +++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 organization/internal-documentation.md diff --git a/organization/index.md b/organization/index.md index 9eec44a..23d3003 100644 --- a/organization/index.md +++ b/organization/index.md @@ -1,3 +1,10 @@ # Organization In this section we will add organizational processes. + +:::{toctree} +:hidden: +:caption: Internal Documentation + +Google Drive +::: diff --git a/organization/internal-documentation.md b/organization/internal-documentation.md new file mode 100644 index 0000000..eaf4dc7 --- /dev/null +++ b/organization/internal-documentation.md @@ -0,0 +1,13 @@ +# Storing internal pyOpenSci documents + +Google Drive, a part of the pyOpenSci Google Workspace plan, is where all pyOpenSci documents, spreadsheets, google slides, photos, and graphics are stored. These documents include, but are not limited to: + +* branding guidelines +* event planning documents +* lesson development drafts and plans, +* slides that support talks and presentations +* and more. + +As a pyOpenSci staff member, you should store any documents related to pyOpenSci in the **pyos-shared** Google Shared Drive. Storing documents in the **pyos-shared** drive ensures that all pyOpenSci employees can access, edit, and use these documents. Storing these documents in the shared drive also supports program task redundancy, as the document's owner is the organization in that drive rather than an individual user. Storing documents in a shared drive owned by the organization helps pyOpenSci staff jump in and help another staff person in the event of a needed but unplanned absence (e.g., a medical emergency or an unexpected family issue). + +Employees can save personal documents such as 1-on-1 agendas and notes, personal notes, and other information that does not need to be shared at the organizational level in their personal drive. From bd0924e9a37c3b9ef24342315875edf728f4aa08 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 20 Aug 2024 16:56:53 -0600 Subject: [PATCH 52/52] fix: make precommit happy with spelling --- community/events/intro.md | 8 +- organization/internal-documentation.md | 2 +- .../meeting-notes/2018/2018-10-09-notes.md | 2 +- .../meeting-notes/2018/2018-12-07-notes.md | 4 +- .../meeting-notes/2019/2019-03-06-notes.md | 2 +- .../2019/2019-03-14-joss-discussion-notes.md | 2 +- .../meeting-notes/2019/2019-05-09-notes.md | 106 +++++++++--------- .../meeting-notes/2019/2019-05-30-notes.md | 2 +- .../meeting-notes/2019/2019-08-01-notes.md | 78 ++++++------- .../meeting-notes/2019/2019-08-22-notes.md | 6 +- .../meeting-notes/2019/2019-09-20-notes.md | 77 ++++++------- .../meeting-notes/2019/2019-10-24-notes.md | 79 ++++++------- .../meeting-notes/2020/2020-04-09-notes.md | 2 +- .../2021-05-17-software-review-scipy-notes.md | 82 +++++++------- 14 files changed, 232 insertions(+), 220 deletions(-) diff --git a/community/events/intro.md b/community/events/intro.md index a2decfc..3b2a631 100644 --- a/community/events/intro.md +++ b/community/events/intro.md @@ -7,11 +7,12 @@ pyOpensci staff regularly attend community meetings (e.g. SciPy meeting, PyCon U In these instances, asynchronous communication and sharing of documents in an organized way is critical. ### Event documents + For every meeting, pyOpenSci staff should create a Google Drive folder, located in our pyos-shared drive, where meeting documents will be stored. These documents may include talk and workshop proposals, attendee signup lists, graphics used in social media and outreach posts and more content related to the event. -Before an event, pyOpenSci staff will make sure this folder is shared and supporting documents are added to it. Often the folder will be created prior to the event to store talk, Bof (birds of a feather), townhall and workshop proposals. +Before an event, pyOpenSci staff will make sure this folder is shared and supporting documents are added to it. Often the folder will be created prior to the event to store talk, BoF (birds of a feather), Townhall and workshop proposals. -:::{admonition} Team checkin prior to an event +:::{admonition} Team check in prior to an event :class: note Staff should also have a short check-in prior to an event to ensure that all documents, and elements needed for the event, are shared in the right place, appropriate permissions are granted, remote support needs for the event are clarified, etc. @@ -40,7 +41,8 @@ Prior to an in-person sprint, the following items should be created: 1. A template "sign up" form, created in HubSpot and shared via a bit.ly shortlink, with data fields that we collect from participants. This allows us to track who attends and event and to followup with them after (if they wish to have communication with us after) 1. A tabletop “card” that says pyOpenSci. You will need 2-3 cards on hand for any event in case participants are spread across a few tables. This card will be important for events like sprints, workshops and open spaces where pyOpenSci has one or more tables in a large room. It will signal to contributors that we are there and help people quickly find us. - * The card should have a qr code that is dynamic (so we can update the url that it points to and reuse the cards). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank you message to each participant using MailChimp or HubSpot. + +* The card should have a qr code that is dynamic (so we can update the url that it points to and reuse the cards). This will allow us to have participants scan the code using their phones, and add their names as participants in the event. Following the event we can then send a thank you message to each participant using MailChimp or HubSpot. :::{todo} will this work for events as we will want an event name associated with it but it would be annoying to make a new card for every event? UNLESS we make a bunch at once for all events for the year? diff --git a/organization/internal-documentation.md b/organization/internal-documentation.md index eaf4dc7..ff2ecdf 100644 --- a/organization/internal-documentation.md +++ b/organization/internal-documentation.md @@ -8,6 +8,6 @@ Google Drive, a part of the pyOpenSci Google Workspace plan, is where all pyOpen * slides that support talks and presentations * and more. -As a pyOpenSci staff member, you should store any documents related to pyOpenSci in the **pyos-shared** Google Shared Drive. Storing documents in the **pyos-shared** drive ensures that all pyOpenSci employees can access, edit, and use these documents. Storing these documents in the shared drive also supports program task redundancy, as the document's owner is the organization in that drive rather than an individual user. Storing documents in a shared drive owned by the organization helps pyOpenSci staff jump in and help another staff person in the event of a needed but unplanned absence (e.g., a medical emergency or an unexpected family issue). +As a pyOpenSci staff member, you should store any documents related to pyOpenSci in the **pyos-shared** Google Shared Drive. Storing documents in the **pyos-shared** drive ensures that all pyOpenSci employees can access, edit, and use these documents. Storing these documents in the shared drive also supports program task redundancy, as the document's owner is the organization in that drive rather than an individual user. Storing documents in a shared drive owned by the organization helps pyOpenSci staff jump in and help another staff person in the event of a needed but unplanned absence (e.g., a medical emergency or an unexpected family issue). Employees can save personal documents such as 1-on-1 agendas and notes, personal notes, and other information that does not need to be shared at the organizational level in their personal drive. diff --git a/reference/meeting-notes/2018/2018-10-09-notes.md b/reference/meeting-notes/2018/2018-10-09-notes.md index b447023..6cad64f 100644 --- a/reference/meeting-notes/2018/2018-10-09-notes.md +++ b/reference/meeting-notes/2018/2018-10-09-notes.md @@ -1,4 +1,4 @@ -# 10 October 2018: JOSS / pyopensci Collaboration +# 10 October 2018: JOSS / pyOpenSci Collaboration Attendees * Leah, Kylen, Arfon diff --git a/reference/meeting-notes/2018/2018-12-07-notes.md b/reference/meeting-notes/2018/2018-12-07-notes.md index c7cf617..e2aef48 100644 --- a/reference/meeting-notes/2018/2018-12-07-notes.md +++ b/reference/meeting-notes/2018/2018-12-07-notes.md @@ -14,12 +14,12 @@ https://hackmd.io/421E2mvqRWy9yHzFGXnueA ## Agenda Items -* pyopensci repo +* pyOpenSci repo * 1-pager - Moore funding * chat with Tracy Teal (Carpentries) * Meet our new GRA!! Kylen! -## pyopensci repo +## pyOpenSci repo * will meet with Stefan (current owner) next week or the week after?? ## Notes from conversation with Tracy diff --git a/reference/meeting-notes/2019/2019-03-06-notes.md b/reference/meeting-notes/2019/2019-03-06-notes.md index 1c20bf8..e59dff6 100644 --- a/reference/meeting-notes/2019/2019-03-06-notes.md +++ b/reference/meeting-notes/2019/2019-03-06-notes.md @@ -38,7 +38,7 @@ Luiz: cookie cutter is a good start. we can iterate in the future as more people - https://goo.gl/HNBmfa - provide home page of dev guide: https://pyopensci.github.io/dev_guide/intro - Leah/Kylen add info to pyopensci.org from dev guide, one pager, etc - - LEAH WILL create pyopensci website and link to pyopensci.org + - LEAH WILL create pyOpenSci website and link to pyopensci.org - provide levels of involvement - minor: sharing of pyOpenSci with colleagues, providing contacts to other packages, coming to BOF at SciPy, add to GitHub organization - medium: come to a meeting, advisory board diff --git a/reference/meeting-notes/2019/2019-03-14-joss-discussion-notes.md b/reference/meeting-notes/2019/2019-03-14-joss-discussion-notes.md index acdcec7..8ce983a 100644 --- a/reference/meeting-notes/2019/2019-03-14-joss-discussion-notes.md +++ b/reference/meeting-notes/2019/2019-03-14-joss-discussion-notes.md @@ -1,4 +1,4 @@ -# pyOpenSci meeting notes: 3-14-2019 JOSS / pyopensci Collaboration +# pyOpenSci meeting notes: 3-14-2019 JOSS / pyOpenSci Collaboration https://hackmd.io/DAiHv0QhRXCBg-P5GtDzJw# diff --git a/reference/meeting-notes/2019/2019-05-09-notes.md b/reference/meeting-notes/2019/2019-05-09-notes.md index 4c6f475..5d985da 100644 --- a/reference/meeting-notes/2019/2019-05-09-notes.md +++ b/reference/meeting-notes/2019/2019-05-09-notes.md @@ -4,11 +4,10 @@ tags: pyopensci, python # pyOpenSci Meeting Notes - 9 May 2019 -https://hackmd.io/ewQZvQdFSteXh3OXJIJPdw + ## Attendees - * Leah Wasser (Earth Lab, CU Boulder) * Kylen Solvik (Earth Lab, CU Boulder) * Lindsey Heagy (Berkeley) @@ -25,12 +24,12 @@ https://hackmd.io/ewQZvQdFSteXh3OXJIJPdw 2. JOSS update -- partnership is in place!! 3. SciPy bof submitted!! 4. Review process -- where should the review template live to make it easier for people to find? - 1. Create issues in package repo ala JOSS or do it all in the software-review repo ala rOpenSci? https://github.com/pyOpenSci/dev_guide/issues/17 - 2. Currently sits: https://www.pyopensci.org/dev_guide/appendices/templates.html#review-template + 1. Create issues in package repo ala JOSS or do it all in the software-review repo ala rOpenSci? + 2. Currently sits: * NEIL -- didn't have an issue finding the template. he'd like to see it in the email AND the comment for the review ... so maybe the editor should do this OR Whedon the bot could do this?? * also in the guidances for reviewers and authors... - * https://pyopensci.discourse.group/ - * Luiz: maybe create a review issue template, so the checklist doesn't need to be copied? example: https://github.com/datrs/hypercore/tree/master/.github/ISSUE_TEMPLATE + * + * Luiz: maybe create a review issue template, so the checklist doesn't need to be copied? example: * have one template for review, another for pre-review, and submissions * Kylen: We have issue templates for submission and pre-submission. Haven't made one for review because they are comments on existing issues, not new issues by themselves. Is there the option to create a comment template? * Luiz: I don't think there is... sorry, I was thinking on the JOSS structure (where there is a pre-review and a review issue) @@ -40,39 +39,40 @@ https://hackmd.io/ewQZvQdFSteXh3OXJIJPdw * [rOpenSci Requirements based on a discussion with Arfon](https://hackmd.io/KxM9HK-eSo-x2nkTOSBeow) * [Notes from meeting with Arfon](https://hackmd.io/Vw2tyNxZQ5-PItkQFTZqhA) * NOAM takes the floor: - * Ropensci is talking with Arfon as well. JOSS requires a zenodo doi, they want to ensure the version of the package is accepted is linked to a DOI. DOI's are relevant for JOSS but not explicitly tracked in the ropensci process. The DOI for the final version in the review is used for JOSS. - * ropensci has a diagnostic package that they use to provide some feedback and it's run on submission in a standardized envt... and the bot will be able to spit out results - * They've had a few scenarios where authors have requested an updated review. It's not practical... because it's resource intensive... - * Current whedon functionality - * * one we get feedback on the bot, send all of the input to karthik, arfon and noam - * Linsdey -- dashboard with whedon -- allows them to look at editor and reviewer loads, etc etc... that is super helpful. JOSS backend might be a google sheet. + * Ropensci is talking with Arfon as well. JOSS requires a zenodo doi, they want to ensure the version of the package is accepted is linked to a DOI. DOI's are relevant for JOSS but not explicitly tracked in the ropensci process. The DOI for the final version in the review is used for JOSS. + * ropensci has a diagnostic package that they use to provide some feedback and it's run on submission in a standardized envt... and the bot will be able to spit out results + * They've had a few scenarios where authors have requested an updated review. It's not practical... because it's resource intensive... + * Current whedon functionality + * * one we get feedback on the bot, send all of the input to karthik, arfon and noam + * Linsdey -- dashboard with whedon -- allows them to look at editor and reviewer loads, etc etc... that is super helpful. JOSS backend might be a google sheet. ## JOSS vs rOpenSci Review process + * JOSS process follows PLOS -- minimal requirements whereas rOpenSci is more intense process. * LEO: JOSS for example doesn't have (automated) test requirements. it's valuable for us to be more strict * LUIZ: especially considering curating packages...we want to give our stamp of approval ## Funding Opportunity support via rOpenSci - * Ropensci applied for funding -- to support methods focused packages - * aggregate, automate and document current ropensci processes - * how to create a review community - * automation - * creating reviewer databases - * Send reminders, etc - create tools to handle this and make it easy for other groups to adopt - * Write standards for software in a way that can be tested - * (Luiz) semi-relevant: https://www.thoughtworks.com/insights/blog/fitness-function-driven-development - - * Noam needs a letter of support by May 16. - * One pager: https://docs.google.com/document/d/1kZStdLA98TvFe1_0r0IuSBPyg-PL_32wBvw599Zu4NM/edit - * Support: - * +1000 (luiz) - * :tada: Lindsey - * This addresses a huge gap! +1 Max - * +1 leah !! - * :thumbsup: Jenny - -6. First package review checkin: Jenny, Neil, Chris (might not make it) +* Ropensci applied for funding -- to support methods focused packages +* aggregate, automate and document current ropensci processes + * how to create a review community + * automation + * creating reviewer databases + * Send reminders, etc - create tools to handle this and make it easy for other groups to adopt + * Write standards for software in a way that can be tested + * (Luiz) semi-relevant: + + * Noam needs a letter of support by May 16. + * One pager: + * Support: + * +1000 (luiz) + * :tada: Lindsey + * This addresses a huge gap! +1 Max + * +1 leah !! + * :thumbsup: Jenny + +6. First package review check-in: Jenny, Neil, Chris (might not make it) * leah followed up with filipe. she will ping him again:) 7. Second package review -- [earthpy](https://github.com/pyOpenSci/software-review/issues/3) @@ -84,39 +84,39 @@ https://hackmd.io/ewQZvQdFSteXh3OXJIJPdw * Levi Wolf (of PySAL, Contextily, and Geopandas) volunteered to be a future reviewer 8. New pre-submission inquiry! [pacifica](https://github.com/pyOpenSci/software-review/issues/2) * Please provide your feedback on whether we should encourage a submission in this document (be mindful this document is public so if you are not comfortable with that please email us or speak up during our meeting!!) - * More info might be helpful here - the provided link is https://github.com/pacifica but, that has many repos. It might be easier to review if we are reviewing one repository, rather than many repositories. - * The core repository is a Docker compose pipeline (https://github.com/pacifica/pacifica) composed of submodules, each of which is a package - maybe this would be hard to review? + * More info might be helpful here - the provided link is but, that has many repos. It might be easier to review if we are reviewing one repository, rather than many repositories. + * The core repository is a Docker compose pipeline () composed of submodules, each of which is a package - maybe this would be hard to review? * rOpenSci has onboarded suites of tools but also didn't accept a tool that wrapped around another language... given that would be outside of our expertise.. * a shiny app would not be accepted nor a larger system - * LUIZ: pyopensci is more for lego blocks vs .. do we want to curate small packages or packages that can work together... - * NOAM: there are different ways that a python "package" could be presented. we might want to define what a package is and means... - * LEO: for python there is a standard packaging schema but you could have say a web app... that has a different structure. PAcifica does seem to have a set of a few sub packages that have standard python packages.. - * Luiz: would we consider jupyter for example... - * NEIL: we need to really define the scope of what creates a package and what we will review... perhaps we need something that refines the scope, the type of package, how it sits within a larger envt, etc... + * LUIZ: pyOpenSci is more for lego blocks vs .. do we want to curate small packages or packages that can work together... + * NOAM: there are different ways that a python "package" could be presented. we might want to define what a package is and means... + * LEO: for python there is a standard packaging schema but you could have say a web app... that has a different structure. PAcifica does seem to have a set of a few sub packages that have standard python packages.. + * Luiz: would we consider jupyter for example... + * NEIL: we need to really define the scope of what creates a package and what we will review... perhaps we need something that refines the scope, the type of package, how it sits within a larger envt, etc... TODO: how do we dfeine the scope of a what a package is.... -9. Development glossary -- anyone want to contribute and where should we place it? https://github.com/pyOpenSci/dev_guide/issues/8 +9. Development glossary -- anyone want to contribute and where should we place it? 10. PyCon open space feedback (Luiz) - - a quickstart (condensed guide) - - nanopore interested in contributing software, might be a good venue - - EBI (European Bioinformatics Institute) has lots of open source packages, but not much marketing - - .org website feedback - - Link discourse to the main page of pyopensci.org: https://pyopensci.discourse.group/ - - .org website -- too overwhelming for someone new?? - - - accept submissions to pyOpenSci that are already JOSS papers? + * a quickstart (condensed guide) + * nanopore interested in contributing software, might be a good venue + * EBI (European Bioinformatics Institute) has lots of open source packages, but not much marketing + * .org website feedback + * Link discourse to the main page of pyopensci.org: + * .org website -- too overwhelming for someone new?? + + * accept submissions to pyOpenSci that are already JOSS papers? * another fast track? * makes sense for the "curated packages" approach - - requirements? - - code coverage? (no) - - ropensci doesn't have a % coverage but automated testing and CI is required. The code coverage is required to be reported. if the coverage is low, you have to justify it to the editor... - - stable versions (semantic versioning?) - - Link to current reqs: https://www.pyopensci.org/dev_guide/packaging/packaging_guide.html#overview - + * requirements? + * code coverage? (no) + * ropensci doesn't have a % coverage but automated testing and CI is required. The code coverage is required to be reported. if the coverage is low, you have to justify it to the editor... + * stable versions (semantic versioning?) + * Link to current reqs: ## To Do Takeaways - For Everyone + 1. Please review the whedon bot requirements and give us feedback 2. email to arfon, karthik and noam about whatever our requirements end up being for whedon. 3. Please review the pacifica submission and provide your input diff --git a/reference/meeting-notes/2019/2019-05-30-notes.md b/reference/meeting-notes/2019/2019-05-30-notes.md index 534e2a0..2943904 100644 --- a/reference/meeting-notes/2019/2019-05-30-notes.md +++ b/reference/meeting-notes/2019/2019-05-30-notes.md @@ -123,7 +123,7 @@ other option - code for science and society -- but neil things they are more foc 1. Updates: 6 packages in the submission queue! -* [pacifica](https://github.com/pyOpenSci/software-review/issues/2) -- we need to make a decision on it. it's an envt / set of tools. So the question at hand is DOES pyopensci accept these types of submissions? Or do we prefer individual submissions at this point. It would be good to decide this week +* [pacifica](https://github.com/pyOpenSci/software-review/issues/2) -- we need to make a decision on it. it's an envt / set of tools. So the question at hand is DOES pyOpenSci accept these types of submissions? Or do we prefer individual submissions at this point. It would be good to decide this week * Luiz: I think it's a good submission in the future, but it's a really hard submission at the moment (due to complexity). * https://github.com/pyOpenSci/software-review/issues/2#issuecomment-494076938 * filipe -- maybe a platform is a bit much for us to review diff --git a/reference/meeting-notes/2019/2019-08-01-notes.md b/reference/meeting-notes/2019/2019-08-01-notes.md index 4517bb2..40992b8 100644 --- a/reference/meeting-notes/2019/2019-08-01-notes.md +++ b/reference/meeting-notes/2019/2019-08-01-notes.md @@ -4,9 +4,10 @@ tags: pyopensci, python # pyOpenSci Meeting Notes - 1 August 2019 - ## Attendees + Please add your name to the list below! + * Leah Wasser - Earth Lab! * Filipe Fernandes - NOAA/IOOS * Daniel Chen - Virginia Tech + RStudio intern @chendaniely @@ -18,49 +19,50 @@ Please add your name to the list below! ## Agenda * BoF Overview! - * ~35 people in attendance + * ~35 people in attendance * First package NBLESS submitted and approved! - * [Discourse discussion on badge](https://pyopensci.discourse.group/t/we-have-our-first-package-through-review-now-we-need-a-badge/) - * [Vote on a badge on discourse!!](https://pyopensci.discourse.group/t/vote-on-a-pyopensci-badge/68) (+) - * Badge vote please + * [Discourse discussion on badge](https://pyopensci.discourse.group/t/we-have-our-first-package-through-review-now-we-need-a-badge/) + * [Vote on a badge on discourse!!](https://pyopensci.discourse.group/t/vote-on-a-pyopensci-badge/68) (+) + * Badge vote please * Current reviews - * [View completed Nbless submission](https://github.com/pyOpenSci/software-review/issues/7) - * Check in on errdapy review & earthpy reviews - * Leah to check in with Luiz about earthpy review - * Updated review of erddapy by Chris and Jenny complete -* Add your github name to be added to the pyopensci repo here - * [chendaniely](https://github.com/chendaniely) - * [MikeTrizna](https://github.com/MikeTrizna) - * [xmnlab](https://github.com/xmnlab) - * [ocefpaf](https://github.com/ocefpaf) - * Check the [People page](https://github.com/orgs/pyOpenSci/people) for a status of public -* Social media checkin?? - * give multiple people to pyopensci for the time being - * twitter bot to retweet @pyopensci - * Send credentials to: - * Chris - * Martin + * [View completed Nbless submission](https://github.com/pyOpenSci/software-review/issues/7) + * Check in on errdapy review & earthpy reviews + * Leah to check in with Luiz about earthpy review + * Updated review of erddapy by Chris and Jenny complete +* Add your github name to be added to the pyOpenSci repo here + * [chendaniely](https://github.com/chendaniely) + * [MikeTrizna](https://github.com/MikeTrizna) + * [xmnlab](https://github.com/xmnlab) + * [ocefpaf](https://github.com/ocefpaf) + * Check the [People page](https://github.com/orgs/pyOpenSci/people) for a status of public +* Social media check-in?? + * give multiple people to pyOpenSci for the time being + * twitter bot to retweet @pyopensci + * Send credentials to: + * Chris + * Martin * Website - * who's involved -- generate this programmatically? pull from the list of anyone in the organization -- someone would have to build this - twitter api / travis -- They do this for jupyter hub .. - * Chris might be able to copy over what jupyter hub does -- https://jupyterhub-team-compass.readthedocs.io/en/latest/team.html#jupyterhub-team read the docs will build it - * Following the all contributors specs!! https://github.com/jupyterhub/team-compass/blob/master/docs/team/contributors-jupyterhub.yaml -- Chris can work on that next - * https://github.com/jupyterhub/team-compass/tree/master/docs/team - * Website -- links that take you to a github search that filters by tag! -- easy quick (Leah can add this!) - * in the future we can automate this + * who's involved -- generate this programmatically? pull from the list of anyone in the organization -- someone would have to build this - twitter api / travis -- They do this for jupyter hub .. + * Chris might be able to copy over what jupyter hub does -- read the docs will build it + * Following the all contributors specs!! -- Chris can work on that next + * + * Website -- links that take you to a github search that filters by tag! -- easy quick (Leah can add this!) + * in the future we can automate this * Create design repository in the org -- and place the images and branding items in it!! (leah can do this as well) * Funding - * pyopensci -- [working draft of 2-3 pager]( https://docs.google.com/document/d/13S_HOGS89Zm1j257gC8Oja_Yol3j6xCp68Sr2Ln5MM0/edit) - * IDEA -- fund a fellowship position that works full time?? or focuses on this organization - * hire them as a contractor -- could be remote, etc - * Martin, Daniel, and Mike are both in DC area -- NIH (National Institute of Health) - * workshop on packaging your project -- to get more exposure - * partnership with Carpentries would be good - * other existing online resources: [ Molecular Sciences Software Institute (MolSSI) materials](https://molssi-education.github.io/CMS-Python-DevOps/) - * Martin - organizer for a local meetup - * Stats Programming DC: https://www.meetup.com/stats-prog-dc/ - * Leah to followup with nunmfocus about sponsorship + * pyOpenSci -- [working draft of 2-3 pager]( https://docs.google.com/document/d/13S_HOGS89Zm1j257gC8Oja_Yol3j6xCp68Sr2Ln5MM0/edit) + * IDEA -- fund a fellowship position that works full time?? or focuses on this organization + * hire them as a contractor -- could be remote, etc + * Martin, Daniel, and Mike are both in DC area -- NIH (National Institute of Health) + * workshop on packaging your project -- to get more exposure + * partnership with Carpentries would be good + * other existing online resources: [Molecular Sciences Software Institute (MolSSI) materials](https://molssi-education.github.io/CMS-Python-DevOps/) + * Martin - organizer for a local meetup + * Stats Programming DC: + * Leah to followup with nunmfocus about sponsorship * Agu event potentially?? Open source software session presentation - * Leo --- ask about something associated with the plenary or something else!! + * Leo --- ask about something associated with the plenary or something else!! * other topics?? + * ** diff --git a/reference/meeting-notes/2019/2019-08-22-notes.md b/reference/meeting-notes/2019/2019-08-22-notes.md index c8e76a6..d81bf87 100644 --- a/reference/meeting-notes/2019/2019-08-22-notes.md +++ b/reference/meeting-notes/2019/2019-08-22-notes.md @@ -48,13 +48,13 @@ David Nicholson 6. funding for someone who can be a full time editor and community person - * FUNDING pyopensci (leah) -- [working draft of 2-3 pager]( https://docs.google.com/document/d/13S_HOGS89Zm1j257gC8Oja_Yol3j6xCp68Sr2Ln5MM0/edit) + * FUNDING pyOpenSci (leah) -- [working draft of 2-3 pager]( https://docs.google.com/document/d/13S_HOGS89Zm1j257gC8Oja_Yol3j6xCp68Sr2Ln5MM0/edit) > [name=Chris H] I can help w/ this in the coming weeks. Do we have an ongoing conversation with Moore on this, or has it been a while since we've discussed with them? I've heard Moore may be stepping back from funding some of this stuff, so we may need to explore other sources > [name=Leah w] Sloan just approached me to review something so i'd be happy to explore both moore and sloan?? Tracy said moore might support this BUT that was ... gosh 6 months ago. maybe we can divide and conquer to decide?? > * ropensci unconference -- could we find sponsors for this ?? (max) - microsoft, rstudio ... * Tania -- microsoft reactors -- leah can email Tania -- san fransi - * https://developer.microsoft.com/en-us/reactor/
 + * https://developer.microsoft.com/en-us/reactor/ * Ivan is at quansight -- they might be able to support an unconference as well... Next steps @@ -91,6 +91,6 @@ ISSUE HERE: https://github.com/pyOpenSci/pyopensci.github.io/issues/4 * add to 2-3 pager text about the unconference event and what type of staff we'd like to have working on this * Luiz will look into the all-contrbutors bot to use in our repo to track who's contributing. -* Luiz will look for two new (potentially) reviewers for earthpy or will checkin with reviewers aout it... +* Luiz will look for two new (potentially) reviewers for earthpy or will check-in with reviewers aout it... * We have two reviewers for pandera: max and ivan, leah will be the editor * Followup on erdapy (leah can ping filipe) diff --git a/reference/meeting-notes/2019/2019-09-20-notes.md b/reference/meeting-notes/2019/2019-09-20-notes.md index 7dd63b2..0729a6c 100644 --- a/reference/meeting-notes/2019/2019-09-20-notes.md +++ b/reference/meeting-notes/2019/2019-09-20-notes.md @@ -1,14 +1,13 @@ --- -tags: pyopensci, python +tags: pyOpenSci, python --- # pyOpenSci Meeting Notes - 20 September Time: 5pm UTC - - ## Attendees + * Leah Wasser (CU Earth Lab, University of CO - Boulder) * Kirstie Whitaker (Alan Turing Institute, London, UK) - no video * Max Joseph (CU Earth Lab, CU Boulder) @@ -23,65 +22,67 @@ Time: 5pm UTC Gitter came up as one way to directly communicate with each other and ask questions that might be quicker than discourse? (related to discussions Ivan) * some people might find using gitter disruptive . but it could good for quick questions. 3. How do we keep our contributor lists up to date? should we do old school pr approach for the time being until the bot works the way we'd like? - * rOpenSci uses airtable: https://github.com/ropensci/software-review/blob/master/README.Rmd#L115-L126 + * rOpenSci uses airtable: -https://github.com/orgs/pyOpenSci/projects/2 + 5. How do people find - * Packages that are under review - * Packages that have been reviewed / accepted? THIS PR would allow people to add their packages via a single page. https://github.com/pyOpenSci/pyopensci.github.io/pull/16 + *Packages that are under review + * Packages that have been reviewed / accepted? THIS PR would allow people to add their packages via a single page. * Maybe it makes sense for editors handling a submission to move the project to new columns (e.g., completed) in the Projects for pyOpenSci -Project setup: https://github.com/orgs/pyOpenSci/projects/2 +Project setup: * so maybe we can followup with them about how they approach this tracking of reviewers...? - For now + * use the project board on github to manage . there is a way to automate it being done -- - * Moving things to the "Done" board automagically: https://help.github.com/en/articles/configuring-automation-for-project-boards - * leah will merge the PR for adding packages to the website -6. Townhall -- we could get one through esip for pyopensci + * Moving things to the "Done" board automagically: + * leah will merge the PR for adding packages to the website + +6. Townhall -- we could get one through esip for pyOpenSci * is anyone going to be at AGU?leo and Lindsey will be there (Joel Hamman and other Pangeo folks?) * oh right! i bet joe will be there!! FEEDBACK + * it's not clear how people can be involved. * how do we make the communication better so people - * if you are jealous of ropensci but are a python user -- you should come - * Luiz: I think this is good, but somewhat niche (how many people know rOpenSci?). I like Daniel approach in the podcast (below), targeting it to data science users in general + * if you are jealous of ropensci but are a python user -- you should come + * Luiz: I think this is good, but somewhat niche (how many people know rOpenSci?). I like Daniel approach in the podcast (below), targeting it to data science users in general Suggestion on Getting Feedback -* Hold a webinar on pyopensci -- and the workflow -* Kirstie -- has a lot of experience with comms and will open - * share the previous notes - https://hackmd.io/B9zy15QZQTiYXiqRnl0ynA#Roles-contribute-httpbitlypyopensci-bof +* Hold a webinar on pyOpenSci -- and the workflow +* Kirstie -- has a lot of experience with comms and will open + * share the previous notes - -8. cookiecutter updates: https://github.com/pyOpenSci/cookiecutter-pyopensci/issues/7#issuecomment-533598294 - - TODO: Max will see whether we can get PyUp to work with the dev_requirements.txt file(s) in the repo +8. cookiecutter updates: + * TODO: Max will see whether we can get PyUp to work with the dev_requirements.txt file(s) in the repo ## Next Steps + * Leah will coordinate a town hall at AGU -* Webinar on what is pyopensci +* Webinar on what is pyOpenSci * Work on communication - * Avoid the perception that we are a closed group operating alone. - * Tweet more about the group, it's open, anyone can come even if you don't have time to volunteer... or if you don't know how you might participate. - * why get involved? - * Anyone can come - * free reviews!! - * If felt like a group coming up with an idea... it's not a finished product, people can contribute to development of it. - * WHO IS PYOPENSCI - * Tweeting from the individual people could be more powerful. People don't know who pyopensci is. messaging. highlight members of the community. - * can our team commit to tweeting from their accounts - - TweetDeck has a team account feature: https://help.twitter.com/en/using-twitter/tweetdeck-teams - * ok we may want our group to tweet from pyopensci and then they could retweet . - -* Schedule a webinar (thanks ivan) on what is pyopensci, who si involved and how can you get involved. -* Start a tweet campaign. everyone on our team writes tweets and pyopensci posts them tagging that user as a way to increate visibility but also put names to who is involved with pyopensci. - + * Avoid the perception that we are a closed group operating alone. + * Tweet more about the group, it's open, anyone can come even if you don't have time to volunteer... or if you don't know how you might participate. + * why get involved? + * Anyone can come + * free reviews!! + * If felt like a group coming up with an idea... it's not a finished product, people can contribute to development of it. + * WHO IS pyOpenSci + * Tweeting from the individual people could be more powerful. People don't know who pyOpenSci is. messaging. highlight members of the community. + * can our team commit to tweeting from their accounts + * TweetDeck has a team account feature: + * ok we may want our group to tweet from pyOpenSci and then they could retweet . + +* Schedule a webinar (thanks ivan) on what is pyOpenSci, who si involved and how can you get involved. +* Start a tweet campaign. everyone on our team writes tweets and pyOpenSci posts them tagging that user as a way to increase visibility but also put names to who is involved with pyOpenSci. ## Other -1. Retweet on pyopensci account: https://twitter.com/TalkPython/status/1166903977235177472 (very nice shoutout!) - - Episode: https://talkpython.fm/episodes/show/227/maintainable-data-science-tips-for-non-developers -2. (Luiz) Unrelated: I saw the conda-forge meeting notes this week, I like the format: https://conda-forge.org/docs/minutes/2019-09-18.html +1. Retweet on pyOpenSci account: (very nice shoutout!) + * Episode: +2. (Luiz) Unrelated: I saw the conda-forge meeting notes this week, I like the format: > [name=Leah Wasser] i like those meeting minutes luiz!! thanks for sharing that. i also love that idea of getting shoutouts from podcast accounts and such!! diff --git a/reference/meeting-notes/2019/2019-10-24-notes.md b/reference/meeting-notes/2019/2019-10-24-notes.md index 86960b6..b501be5 100644 --- a/reference/meeting-notes/2019/2019-10-24-notes.md +++ b/reference/meeting-notes/2019/2019-10-24-notes.md @@ -4,7 +4,6 @@ tags: pyopensci, python # pyOpenSci Meeting Notes - 24 october 2019 - ## Attendees * Leah Wasser - Earth Lab University of Colorado, Boulder @@ -15,38 +14,38 @@ tags: pyopensci, python ## Agenda -* Review checkin: - * Pandera is APPROVED / accepted!! - * blog TBD - * earthpy -- under review?? - * Next package to review?? -- martin has 2 others as presubmissions. we could begin reviewing - * ping twitter -- for more submissions?? - * Max would be happy to work on `rmdawn` (editor) - * Next steps (Max): - * Contact Martin to get a submission PR open - * Find reviewers (ping rOpenSci slack channel) +* Review check-in: + * Pandera is APPROVED / accepted!! + * blog TBD + * earthpy -- under review?? + * Next package to review?? -- martin has 2 others as presubmissions. we could begin reviewing + * ping twitter -- for more submissions?? + * Max would be happy to work on `rmdawn` (editor) + * Next steps (Max): + * Contact Martin to get a submission PR open + * Find reviewers (ping rOpenSci slack channel) * Add your name to the website as a contributor please: - * Do this now if you are game??!! https://github.com/pyOpenSci/pyopensci.github.io/blob/master/_data/contributors.yml - * It will be posted here once merged: https://www.pyopensci.org/contributors/ - * please update this file with your info: https://github.com/pyOpenSci/pyopensci.github.io/blob/master/_data/contributors.yml - * Pull request from chris: https://github.com/pyOpenSci/pyopensci.github.io/pull/24 - * JOSS LANGUAGE HERE: https://github.com/pyOpenSci/pyopensci.github.io/pull/24/files#diff-2143091391115ad4c04dc0658967bad4R65 - * pyopensci is trying to improve the ecosystem of python packages... - * max left some comments about what packages might be considered for JOSS... -* Repo metadata specs discussion (Chris?): https://pyopensci.discourse.group/t/finding-a-specification-for-repository-metadata/119 + * Do this now if you are game??!! + * It will be posted here once merged: + * please update this file with your info: + * Pull request from chris: + * JOSS LANGUAGE HERE: + * pyOpenSci is trying to improve the ecosystem of python packages... + * max left some comments about what packages might be considered for JOSS... +* Repo metadata specs discussion (Chris?): * Codemetapy -- tool to create the json codemeta file... - * we can give people some guidelines to ensure that the correct metadata are in the setup.py or codemeta.json file - * this might the ideal with pre-commit hooks to update that JSON file which luiz mentioned might be an issue - * This might be an opportunity to contribute back to the codemetapy package. - * Next steps - * come up with the metadata fields that we want for python packages - * codemeta.json -- do we require this or is it optional ?? rOpenSci recommends using a codemeta.json file. - * Can we provide instructions for setting up a pre-commit hook for users who want to ensure their json is always up to date. - * ropensci makes codemeta a recommendation not a requirement.. - + * we can give people some guidelines to ensure that the correct metadata are in the setup.py or codemeta.json file + * this might the ideal with pre-commit hooks to update that JSON file which luiz mentioned might be an issue + * This might be an opportunity to contribute back to the codemetapy package. + * Next steps + * come up with the metadata fields that we want for python packages + * codemeta.json -- do we require this or is it optional ?? rOpenSci recommends using a codemeta.json file. + * Can we provide instructions for setting up a pre-commit hook for users who want to ensure their json is always up to date. + * ropensci makes codemeta a recommendation not a requirement.. ## Badges -- do we want a review with a version stamp on it + * for records -- we should specify the version of the package that was review. * the package badge should have the version that was reviewed... * how do we deal with the dynamic nature of software dev? @@ -56,34 +55,36 @@ tags: pyopensci, python * what is people who submit and have packages approved -- they agree to check in on packages that were already reviewed to see if updates were made. IDEA: add the version that was reviewed to this file?? -https://github.com/pyOpenSci/pyopensci.github.io/blob/master/_data/packages.yml + *** let's add this as a discourse topic ... Another stream of consciousness thought: Crev is a software review system that I've seen used in the Rust ecossystem. Seems like it could be path forward for 'permanent review' that accounts for new versions? -More info: https://wiki.alopex.li/ActuallyUsingCrev +More info: ## Notes for Existing Maintainers + * if we have changes -- the expectations should be that even approved packages should accommodate these updates. * should we have an area on the discourse site for maintainers?? we need a way to communicate with maintainers over time! * let's look into this From Chris: For the metadata conversation, I think the main question to ask is: do we want to define a minimal amount of metadata that repositories need to have? I don't see anything like this in the rOpenSci packaging guide. We could also try piggy-backing off of fields in the DESCRIPTION file specification. I think most of those files probably already exist in Python's `setup.py` spec, so I think in the short-term we should just tell authors to use that (maybe we also allow pyproject.toml etc, but treat it as an advanced use-case that we don't provide documentation about). + * Pyopensci Blog (Ivan) - * Initial thoughts: https://hackmd.io/RX2nz6WFSm-RjHyOIsmTnA + * Initial thoughts: * Website update: FAQ that explains who we are vs joss - * Other ideas to community who we are as there is some confusion on twitter + * Other ideas to community who we are as there is some confusion on twitter * PyOpenSci Google Calendar (Ivan)? - * Maybe would be good to have a public calendar - * + * Maybe would be good to have a public calendar + * * PyOpenSci introduction slides? - * Is there already any slides that has some introduction about PyOpenSci? It would help us to spread the word in conferences, communities meeting or internally in our jobs. - * NEXT MEETING!!! - + * Is there already any slides that has some introduction about PyOpenSci? It would help us to spread the word in conferences, communities meeting or internally in our jobs. + * NEXT MEETING!!! ## Community feedback + * Not enough activity / things going on... seems quiet * We could write content on the blog -- about what we are doing!! - * we could get reviewers and editors to contribute too - * Sasha -- something more numerical... numpy pandas, etc!! physics background. + * we could get reviewers and editors to contribute too + * Sasha -- something more numerical... numpy pandas, etc!! physics background. diff --git a/reference/meeting-notes/2020/2020-04-09-notes.md b/reference/meeting-notes/2020/2020-04-09-notes.md index 1510eb7..1276f04 100644 --- a/reference/meeting-notes/2020/2020-04-09-notes.md +++ b/reference/meeting-notes/2020/2020-04-09-notes.md @@ -33,6 +33,6 @@ tags: pyopensci, python obspy -- we should make a decision Provide a few options for him to fix this issue: -* Are there options to pull out pieces of it for pyopensci vs io stuff that might be more difficult to get passing tests? +* Are there options to pull out pieces of it for pyOpenSci vs io stuff that might be more difficult to get passing tests? * Are there things we could do to support them in fixing the test like mocking servers... * diff --git a/reference/meeting-notes/2021/2021-05-17-software-review-scipy-notes.md b/reference/meeting-notes/2021/2021-05-17-software-review-scipy-notes.md index 043ad0b..c91d4b4 100644 --- a/reference/meeting-notes/2021/2021-05-17-software-review-scipy-notes.md +++ b/reference/meeting-notes/2021/2021-05-17-software-review-scipy-notes.md @@ -2,38 +2,44 @@ ###### tags: `Meeting` - - **Date:** Nov 1, 2030 2:30 PM (CET) - **Agenda** + 1. Software Review sync `10min` 2. Editorial Board `20min` - + domain area "buckets" - + how to find editors for each "bucket" - + onboarding + +- domain area "buckets" +- how to find editors for each "bucket" +- onboarding + 4. SciPy mentored sprints `15min` -- **Participants:** - - Leah Wasser (LW) - - Ivan Ogasawara (OW) - - David Nicholson (DN) +- **Participants:** + - Leah Wasser (LW) + - Ivan Ogasawara (OW) + - David Nicholson (DN) ## Notes -1. softare review sync - + devicely - + ask on twitter about reviewers - + OW: could act as reviewer, worked on related tool - + pymedphys - + LW: pymedphys -- actually a set of tools - similar to astropy - + some issues we should close - close all of the old presumbissions +1. software review sync + +- devicely + - ask on twitter about reviewers + - OW: could act as reviewer, worked on related tool +- pymedphys + - LW: pymedphys -- actually a set of tools - similar to astropy +- some issues we should close - close all of the old presumbissions + 2. editorial board - + Lets start with Ivan, David and Leah - + We might consider domain "buckets" - + ROpenSci + JOSS like model - + who do we want, how long do they serve - + we have onboarded them + +- Lets start with Ivan, David and Leah +- We might consider domain "buckets" +- ROpenSci + JOSS like model +- who do we want, how long do they serve +- we have onboarded them ## Action Items + - LW: close older issues w/invitation to submit - LW: will get back to simon about PyMedPhys - DN: add suggestion to editor guide to update initial comment w/reviewers etc. so it's right at top of issue @@ -42,29 +48,29 @@ - DN: follow up w/LW + IO about mentored sprints at SciPy ## SciPy Mentored Sprints (David) - Tania Allard -* they are doing these springs at pycon - * https://mentored-sprints.netlify.app/ - * https://www.youtube.com/watch?v=SGUHyP8ki_Q -* could we use pyopensci maintainers to participate in the mentored sprints? - * Have them bring friends who can contribute to the sprints? - * maintainers would need to identify things to fix - * Then they would come to the sprint - * Do they have to register for scipy? - * sprints are run in discord - * git help desk - * maintainers volunteer time to - * find issues ahead of time - * work with people who want to submit PRs - * ask them to do things that aren't code contributions like run through a tutorial and raise issues, etc. - * Open science labs - they do hae training materials already in (spanish?) +* they are doing these springs at pycon + - + - +- could we use pyOpenSci maintainers to participate in the mentored sprints? + - Have them bring friends who can contribute to the sprints? + - maintainers would need to identify things to fix + - Then they would come to the sprint + - Do they have to register for scipy? + - sprints are run in discord + - git help desk + - maintainers volunteer time to + - find issues ahead of time + - work with people who want to submit PRs + - ask them to do things that aren't code contributions like run through a tutorial and raise issues, etc. + - Open science labs - they do hae training materials already in (spanish?) Challenges with mentored sprints -* getting envt setup -* knowing what issue to work on - +- getting envt setup +- knowing what issue to work on ## Outcomes + we will go to scipy and SPY ducky app for video chat?!