|
| 1 | +# Review process: Python Packaging Guidebook |
| 2 | + |
| 3 | +pyOpenSci maintainers a [Python packaging guidebook](https://www.pyopensci.org/python-package-guide/) that provides |
| 4 | +recommendations and best practices for creating and sharing Python code. |
| 5 | +Open source software and shared code are critical pieces of open science and of making science more collaborative. |
| 6 | + |
| 7 | +While pyOpenSci seeks to support the broader scientific community, it is |
| 8 | +important that our content is also accessible and beginner-friendly. Accessible content allows more people to participate in science and is core to our goals of creating diverse community that is empowered in the open science ecosystem. |
| 9 | + |
| 10 | +pyOpenSci has a review process that ensures all of it's online content is: |
| 11 | + |
| 12 | +* accurate |
| 13 | +* accessible and |
| 14 | +* beginner-friendly. |
| 15 | + |
| 16 | +This page overviews that process. |
| 17 | + |
| 18 | +## Scope |
| 19 | +This governance applies to all technical content created for the Python Packaging Guidebook and associated tutorials. |
| 20 | + |
| 21 | +## Roles and Responsibilities |
| 22 | + |
| 23 | +There are several "types" of contributors that are critical to achieving the guidebook's above-stated goals. |
| 24 | + |
| 25 | +- **Content Authors**: Write early drafts with research to ensure accuracy. Engage with content experts for initial reviews. |
| 26 | +- **Content Experts**: Provide early feedback on drafts to ensure technical accuracy. This feedback may be in person, or online via direct message / group chats. This feedback is critical to ensuring the initial drafts capture important topics and concepts. |
| 27 | +- **Community Reviewers**: Participate in the GitHub pull request review process, |
| 28 | + providing feedback within the designated review period. |
| 29 | +- **Moderators**: Oversee the review process, manage conflicts, and ensure that the |
| 30 | + final content meets user needs and standards of accessibility. |
| 31 | +- **Decision-Makers**: Facilitate consensus and make final decisions on content approval. Typically the Executive Director of pyOpenSci makes final decisions when consensus can't be made. But more often the community is able to achieve consensus. |
| 32 | + |
| 33 | +## Review Process |
| 34 | + |
| 35 | +### Early Draft Creation |
| 36 | +- **Research and Writing**: Authors conduct thorough research and write early drafts. |
| 37 | + Initial drafts should aim for technical accuracy and clarity. |
| 38 | +- **Early Expert Review**: Drafts are reviewed by content experts for accuracy and |
| 39 | + technical soundness. Feedback is incorporated to refine the content. |
| 40 | + |
| 41 | +### GitHub Pull Request and Community Review |
| 42 | +- **Pull Request Submission**: A polished version of the draft is submitted as a pull |
| 43 | + request on GitHub. |
| 44 | +- **Review Timeline**: The community review period is set for 1-2 weeks. Reviewers are |
| 45 | + encouraged to provide feedback on clarity, accuracy, and accessibility. |
| 46 | +- **Feedback Collection**: All review comments are documented and addressed by the |
| 47 | + authors. |
| 48 | + |
| 49 | +### Second Review Round (If Necessary) |
| 50 | +- **Revision**: If feedback is extensive, authors revise the document based on reviewer |
| 51 | + comments. |
| 52 | +- **Second Review**: A second round of community review is held for an additional 1-2 |
| 53 | + weeks. |
| 54 | + |
| 55 | +### Finalization and Merging |
| 56 | +- **Consensus Building**: Moderators facilitate discussions to reach general consensus |
| 57 | + among reviewers. |
| 58 | +- **Conflict Resolution**: If disagreements arise, moderators mediate to resolve |
| 59 | + conflicts, ensuring the content meets user needs. |
| 60 | +- **Content Merging**: Once consensus is achieved, the content is merged into the |
| 61 | + guidebook. |
| 62 | + |
| 63 | +## 4. Conflict of Interest Policy |
| 64 | +- **Disclosure**: All participants in the review process must disclose any potential |
| 65 | + conflicts of interest, including promotion of tools they work on, authored, or |
| 66 | + maintain. |
| 67 | +- **Management**: Conflicts of interest are managed to maintain the integrity and |
| 68 | + fairness of the review process. |
| 69 | + |
| 70 | +## 5. Documentation and Transparency |
| 71 | +- **Record Keeping**: All reviews, feedback, and revisions are documented and archived. |
| 72 | +- **Transparency**: Information about the review process and decisions is made available |
| 73 | + to the community. |
| 74 | + |
| 75 | +## 6. Appeals Process |
| 76 | +- **Grounds for Appeal**: Appeals can be made based on procedural errors or overlooked |
| 77 | + critical feedback. |
| 78 | +- **Appeal Procedure**: Appeals must be submitted in writing within two weeks of the |
| 79 | + decision. The appeal will be reviewed by a separate panel of reviewers. |
| 80 | + |
| 81 | +## 7. Review and Revision of Governance |
| 82 | +- **Periodic Review**: The governance document is reviewed annually to ensure it remains |
| 83 | + effective and relevant. |
| 84 | +- **Feedback Mechanism**: A system for collecting feedback on the review process from |
| 85 | + participants is established to continuously improve the process. |
| 86 | + |
| 87 | +## Conclusion |
| 88 | +This governance document ensures a structured, transparent, and fair review process for |
| 89 | +the Python Packaging Guidebook, emphasizing accuracy, accessibility, and user-centered |
| 90 | +content development. By following these guidelines, we aim to produce high-quality, |
| 91 | +beginner-friendly, and technically accurate documentation that serves the needs of our |
| 92 | +users. |
0 commit comments