diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5d3cbb5..9855ebc 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -37,3 +37,8 @@ repos: rev: v2.3.0 hooks: - id: codespell + + - repo: https://github.com/errata-ai/vale + rev: v3.7.0 + hooks: + - id: vale diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..ae90e8c --- /dev/null +++ b/.vale.ini @@ -0,0 +1,32 @@ +# Configuration file for using Vale in the python-package-guide repository +# +# To disable checks on parts of a MarkDown or HTML file, delimit the section +# using these HTML comments: +# to disabled Vale checks after this line: +# to enable Vale checks after this line: +# +# To disable checks based on MarkDown scope, see IgnoredScopes. +# To disable checks on certain HTML elements, see IgnoredClasses. +# +# More information about the configuration can be found here: +# https://vale.sh/docs/topics/config + + +# Path to the styles directory, where style rules are defined +StylesPath = vale-styles + +# Path to a dictionary folders inside the StylesPath config subdirectory. This +# folder can contain two files, accept.txt and reject.txt, with one word per +# line. These words will be used to check for spelling mistakes in addition to +# the internal dictionary, if the 'Vale' ruleset is enabled (see below) +# See https://vale.sh/docs/topics/vocab/#folder-structure for more details +Vocab = sample + + +# Checks are defined in sections by file type, like the one below for +# MarkDown. In each section you can enable groups of style rules, defined in folders +# inside the StylesPath directory. +# Use 'Vale' to enable the internal style rules and checks. + +[*.md] +BasedOnStyles = pyos-styles diff --git a/community/events/sprints.md b/community/events/sprints.md index 65ee113..682c448 100644 --- a/community/events/sprints.md +++ b/community/events/sprints.md @@ -1,34 +1,35 @@ # 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. + +* TODO: i think we want to set this up for all repositories so this works for scipy. ::: :::{admonition} TL;DR **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 [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. +* pyOpenSci staff go through the pyOpenSci repository issues and ensure all relevant **help-wanted** and **printable** have appropriated labels and have been added to the [GitHub project](GitHub-project) in the appropriate column (beginner-friendly, Python, dev-ops/ci, Python, Sphinx). +* pyOpenSci staff ensures 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 whoever 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. +* Label all newly submitted issues as `sprint-event` +* Merge small PRs that are mergeable without significant review. Examples 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). [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 +* **IMPORTANT:** Be sure to add all contributors to each repo they've contributed to using the all-contributors bot. Merge the PR immediately after it is opened and before another contributor is added to avoid merge conflicts. **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 +Triage issues and pull requests. + • Ensure that all contributors are added to each repository they've contributed to using the all-contributors bot. + • Prioritize replying to, addressing, and merging pull requests. If an issue has a lingering TODO, tag it with a help-wanted label for a future sprint. + • Send follow-up thank you notes. + • Collect, process, and aggregate sprint metrics. ::: - ## 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: @@ -37,17 +38,18 @@ There are three types of pyOpenSci sprint events: 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 +During pyOpenSci sprints, contributors need tasks that are "sprintable." +`Sprintable` tasks 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. +Sprints last 1-5 days but are usually 1-2 days long. PyCon US sprints last an entire week, and SciPy meeting sprints last two days on the weekend. ### 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: + +Contributors frequently open numerous pull requests and issues during pyOpenSci sprint events. It's essential for pyOpenSci to track information around the following: * Who is attending, -* Where they are from (country, state etc) and +* Where they are from (country, state, etc.) and * What contributions they make. This information will support pyOpenSci's community impact and support and be @@ -59,22 +61,19 @@ pyOpenSci uses a combination of GitHub project boards and user surveys to track Sprint participants are often motivated by different things. Some come to: -* learn -* help and support a project they care about -* connect and build community +* Learn +* Help and support a project they care about +* Connect and build community -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 +pyOpenSci supports and empowers all of the above motivations. We thrive on empowering new contributors to make their first (or second) contributions to open source! 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 -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. +PyOpenSci should always be accessible to new and seasoned contributors, aligning with our mission, vision, and values. We aim to ensure that all participants have a successful experience within our community. Some participants are new and may be submitting their first-ever issue or pull request to an open-source project. + These participants: * may need help using git and GitHub, or @@ -86,55 +85,55 @@ 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 most cases having community helpers will go along way to supporting beginner contributor success. +As such, it's essential for anyone leading a sprint to come prepared! In most cases, having community helpers will go a long way toward supporting beginner contributor success. (github-project)= + ## Sprint infrastructure - GitHub projects To efficiently manage and track contributions during sprints, pyOpenSci utilizes -[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. +[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. Label any discrete task that someone could complete during a sprint as `sprintable`. An organized project ensures that contributors, whether new or experienced, can easily find and work on tasks that suit their skills and interests. :::{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. +We also are testing out using [event projects](https://github.com/orgs/pyOpenSci/projects/12) 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 -find tasks that pyOpenSci needs help with. We have two automated workflows setup -for the help-wanted project board: +find tasks that pyOpenSci needs help with. We have two automated workflows set up for the [help-wanted project board](https://github.com/orgs/pyOpenSci/projects/3): * 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 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. Someone on the pyOpenSci team should update the project board throughout the year as new issues are opened in our organization's GitHub repositories. Continual updates make 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. +* Sprint leaders to prepare for a sprint as the board will be more up-to-date. #### 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). +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 of 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`. pyOpenSci uses this project board 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 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. +* **Manage the Triage Process**: Track 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. -### Year round sprint tasks +These boards allow pyOpenSci staff to easily monitor sprint activities and outcomes, enabling timely resolution of all sprint issues and pull requests. -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. +### Year-round sprint tasks + +Below are tasks to stay on top of throughout the year. By adding "sprintable" and "help-wanted" issues to the help-wanted project board as they are opened, you save time spent preparing for a sprint. #### Maintain the pyOpenSci help-wanted project board @@ -147,27 +146,26 @@ 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). + 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. + 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 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 +* 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. @@ -196,7 +194,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. + 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 @@ -217,13 +215,11 @@ 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} -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. +NOTE: i have setup this workflow 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! @@ -236,7 +232,6 @@ Jesse will flesh this out when it's ready! jesse will develop this process with whatever platform we end up using... ::: - ## Tasks during a sprint Below are tasks that should occur during a sprint event. @@ -271,13 +266,13 @@ 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 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” +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 ::: ### Review and triage pull requests and issues -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 +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. :::{todo} @@ -285,6 +280,7 @@ 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) @@ -305,7 +301,6 @@ If they have opened an issue only, or reviewed an open pull request use: If they have opened a pull request use: `@all-contributors add @githubusername for code, review` - 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. @@ -315,12 +310,13 @@ community, encouraging more participation and collaboration. ## 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. +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. @@ -337,19 +333,20 @@ 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](https://eepurl.com/iM7SOM) - to stay updated on future events, news, and opportunities. - - **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 + * **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](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](https://github.com/pyopensci). :::{todo} - - Discourse? + +* Discourse? ::: 4. **Stay Connected**: - - **Upcoming Events**: Inform participants about upcoming sprints, webinars, - workshops, or any other events they might be interested in. + * **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 fostering a sense of community, and encourage ongoing contributions to pyOpenSci projects. @@ -371,15 +368,15 @@ 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 / organization) - * Type of user - student, professional, non profit/ public sector. - * Optional - demographics + * Where are the contributors from (country, place of work / organization) + * Type of user - student, professional, non profit/ public sector. + * Optional - demographics ::: - :::{todo} SPRINTS: Collecting information during - sprints, etc - process so we can work together? GDPR compliant database diff --git a/community/index.md b/community/index.md index f390cba..edb286e 100644 --- a/community/index.md +++ b/community/index.md @@ -1,15 +1,26 @@ -# Organization Handbook +# Community Handbook + +pyOpenSci has built a vibrant open science community of practice. This +community: + +1. helps scientists develop the open science skills needed to make their workflows more open and collaborative. +2. runs a Python software peer review process that reviews scientific software. +3. partners and leverage the work of other communities so we can learn and move forward together. + +In this section of the handbook, we describe the platforms, processes and +approaches that we use to engage with both scientists and the broader +scientific Python community. :::{toctree} -:hidden: -:caption: Social Media Section +:maxdepth: 2 +:caption: Social Media Social Media Slack ::: :::{toctree} -:hidden: +:maxdepth: 2 :caption: GitHub Processes GitHub @@ -20,7 +31,7 @@ Continuous Integration (CI) ::: :::{toctree} -:hidden: +:maxdepth: 2 :caption: pyOpenSci Events Events diff --git a/reference/index.md b/reference/index.md index b28d435..b1d92e7 100644 --- a/reference/index.md +++ b/reference/index.md @@ -3,8 +3,6 @@ pyOpenSci began officially meeting in the fall of 2018. Below are the meeting notes from those early meetings. - - ```{toctree} --- caption: All Meeting Notes @@ -16,3 +14,10 @@ maxdepth: 1 2019 Notes 2018 Notes ``` + +:::{toctree} +caption: Executive Council Minutes +maxdepth: 1 + +2024 Minutes +::: diff --git a/vale-styles/config/vocabularies/sample/accept.txt b/vale-styles/config/vocabularies/sample/accept.txt new file mode 100644 index 0000000..e69de29 diff --git a/vale-styles/config/vocabularies/sample/reject.txt b/vale-styles/config/vocabularies/sample/reject.txt new file mode 100644 index 0000000..e69de29 diff --git a/vale-styles/pyos-styles/PyPI.yml b/vale-styles/pyos-styles/PyPI.yml new file mode 100644 index 0000000..4c6ef40 --- /dev/null +++ b/vale-styles/pyos-styles/PyPI.yml @@ -0,0 +1,28 @@ +extends: substitution +message: Consider using '%s' instead of '%s' +level: warning +ignorecase: false +action: + name: replace +# swap maps tokens in form of bad: good +swap: + # lower case defined as regex to prevent false positives in URLs or other identifiers + - (?:\spypi[\.,]?\s): PyPI + - (?:\stestpypi[\.,;:]?\s): TestPyPI + - (?:\stest-pypi[\.,;:]?\s): TestPyPI + - \bpyopensci\b: pyOpenSci + - \bPyOpenSci\b: pyOpenSci + # other tests are defined with strings + - pyPi: PyPI + - pyPI: PyPI + - PYPI: PyPI + - PyPi: PyPI + - Pypi: PyPI + - testPyPI: TestPyPI + - testPYPI: TestPyPI + - TestPypi: TestPyPI + - TestPYPI: TestPyPI + - back-end: backend + - back end: backend + - front-end: frontend + - front end: frontend