|
| 1 | +# pyOpenSci GitHub issue process |
| 2 | + |
| 3 | +When possible, pull request and issue submissions and reviews should follow |
| 4 | +standard open source workflows. Below are guidelines for handling issues. |
| 5 | + |
| 6 | +## Guidelines for New Issues |
| 7 | + |
| 8 | + |
| 9 | +**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 |
| 10 | +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. |
| 11 | + |
| 12 | +To ensure an issue is well-written and specific, include the following details: |
| 13 | + |
| 14 | +- **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 |
| 15 | + |
| 16 | + * `Bug: broken link in link-to-page-here / name of page / document etc` |
| 17 | + * `Fix: confusing paragraph on Python packaging with Hatch` |
| 18 | + * `Add: page on using pixi for dependencies` |
| 19 | + |
| 20 | +- **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. |
| 21 | + |
| 22 | +- **Screenshots/Code Samples:** Screenshots, code snippets, links, or any other relevant files that can help in understanding the issue better. |
| 23 | + |
| 24 | +- **Possible Solutions/Recommendations:** Any ideas or suggestions for how to address the issue, which can help guide contributors towards a solution. |
| 25 | + |
| 26 | +- **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. |
| 27 | + |
| 28 | +### If you are reporting a code bug |
| 29 | + |
| 30 | +* **Steps to Reproduce (for bugs):** A step-by-step guide on how to reproduce the issue, including relevant code snippets, commands, or configurations. |
| 31 | + |
| 32 | +* **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. |
| 33 | + |
| 34 | +* **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. |
| 35 | + |
| 36 | +### If you have permissions, label the issue |
| 37 | + |
| 38 | +While outside contributors will not have permission to label issues, pyOpenSci core team members and volunteers will. Be sure to add appropriate labels to |
| 39 | +issues to make it easier to triage them. |
| 40 | + |
| 41 | +## Help-wanted / sprintable issues |
| 42 | + |
| 43 | +If an issue is something that anyone in the community could potentially |
| 44 | +address, it's ideal to label the issue with `help-wanted` and/or `sprintable`. |
| 45 | +A sprintable issue refers to an issue that could be completed or worked on |
| 46 | +during a 1-2 day sprint, thus it should be smaller and more confined in scope. |
| 47 | +A help-wanted issue is one that anyone is welcome to work on during whatever |
| 48 | +time they have available. |
| 49 | + |
| 50 | +Once the `help-wanted` or `sprintable` issue label is added, the issue will be |
| 51 | +automatically added to our |
| 52 | +[pyOpenSci help-wanted board](https://github.com/orgs/pyOpenSci/projects/3). |
| 53 | +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. |
| 54 | + |
| 55 | + |
| 56 | +:::{note} |
| 57 | +The issue will be archived from the project board once it is closed. |
| 58 | +::: |
| 59 | + |
| 60 | + |
| 61 | +:::{todo} |
| 62 | +Add link to sprints page when it's online |
| 63 | +::: |
| 64 | + |
| 65 | +If an issue is unclear, a pyOpenSci staff member or designated community |
| 66 | +member can ask the issue author to provide more information. |
| 67 | + |
| 68 | + |
| 69 | + |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +:::{todo} |
| 74 | +Add section on labels |
| 75 | +::: |
| 76 | + |
| 77 | +## Issue Maintenance |
| 78 | + |
| 79 | +Our goal at pyOpenSci is to keep our list of issues current and active. |
| 80 | +Quarterly issue cleanup sessions should be implemented to ensure issues are |
| 81 | +either being actively addressed or to assess whether older or stale issues can |
| 82 | +be potentially closed. |
0 commit comments