diff --git a/mkdocs.yml b/mkdocs.yml index 19489f0a1..80dae895b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -68,7 +68,11 @@ nav: - Overview: "opportunities/gsoc/index.md" - Project Ideas: "opportunities/gsoc/project-ideas/index.md" - "Contribution Guidelines": "opportunities/guides/contribution/index.md" - - "Candidates' Guide": "opportunities/gsoc/guides/contributor/index.md" + - "Coding Tips": "opportunities/guides/coding-tips/index.md" + - "Guides Overview": "opportunities/gsoc/guides/contributor/index.md" + - "Organization Admins Guide": "opportunities/gsoc/guides/organization-admins/index.md" + - "Mentors Guide": "opportunities/gsoc/guides/mentors/index.md" + - "Contributor Candidates Guide": "opportunities/gsoc/guides/candidates/index.md" - "Template: Project Idea": "opportunities/gsoc/templates/project-ideas.md" - "Template: Candidates Project Proposal": "opportunities/gsoc/templates/contributor-proposal.md" - Partnership: diff --git a/pages/opportunities/gsoc/guides/candidates/index.md b/pages/opportunities/gsoc/guides/candidates/index.md new file mode 100644 index 000000000..180f79b3e --- /dev/null +++ b/pages/opportunities/gsoc/guides/candidates/index.md @@ -0,0 +1,115 @@ +# GSoC Guide for Contributor Candidates + +These are Open Science Labs' (OSL) general recommendations for projects and +sub-organizations participating in Google Summer of Code (GSoC) under the OSL +umbrella. Organization admins and maintainers can use, adapt, or incorporate +these recommendations partially or completely into their own project guidelines. +Contributors: also read the guidelines of the project you are contributing to. +Official GSoC rules and applicable codes of conduct still apply. + +## Start in the Community's Preferred Channel + +Find the project's preferred community app or channel and use it for your first +contact. Introduce yourself, explain your interests, and ask: + +- Does the organization intend to participate in the upcoming GSoC edition? +- Which of its projects or project ideas are planned to participate? +- Where can I find the relevant documentation and discuss getting started? + +Ask about the team's plans for the upcoming GSoC edition rather than assuming +participation based on a previous year. Choose a project that aligns with your +interests, skills, and learning goals. Allow time for replies and keep technical +questions in the community channel so others can learn and help. + +## Spend Time Using the Software + +Use the software as a user before rushing to change its code. Spend several days +exploring it, follow the documentation, and try it on a real task or a need you +understand. For a tool or library, test different contexts and use cases rather +than stopping after one quick-start example. + +Discuss your experience with colleagues, other users, and the community. Ask +questions, compare approaches, and understand why existing workflows work as +they do. Keep notes about examples, strengths, confusing steps, and limitations. +Hands-on experience helps you identify useful improvements and explain why they +matter to users. + +## Write About Your Experience as a User + +Before opening a pull request, write a blog post or newcomer experience report +covering: + +- The project's mission, main objectives, and intended users. +- What you used it for, why you chose those tasks, and the contexts you + explored. +- How to install or access it, with reproducible examples for other newcomers. +- What works well and which features or workflows you found useful. +- What was confusing, what could work better, and any setup or documentation + obstacles. +- Constructive suggestions, questions discussed with others, and what you + learned. + +Take time to develop observations from actual use. Write an honest account with +specific examples. Follow the announced submission process; a draft or Markdown +document shared with the team is enough when public publication is not +requested. If setup fails, document what you tried and where you became blocked. + +Then agree on a small follow-up contribution with a mentor, such as improving +onboarding documentation, adding a test, or fixing a bug. Focus on useful work +and responding to feedback rather than maximizing the number of pull requests. + +## Prepare Your Proposal + +Develop a detailed proposal with mentor feedback that explains: + +- **Impact:** How the work advances the project's goals and helps its users. +- **Plan:** Specific tasks, deliverables, milestones, timeline, and risks. +- **Availability:** Time commitments and planned absences. +- **Newcomer Insight:** An observation from using the software and a suggested + improvement. + +Use clear, concise language. Follow the published AI-use policy, disclose +assistance as required, and verify everything you submit. Write a proposal that +reflects your own understanding and be prepared to explain your choices. + +Review the [official rules](https://summerofcode.withgoogle.com/rules), the +selection checklist, and the +[assessment rubric](../organization-admins/index.md#give-community-engagement-explicit-weight) +before applying. Use the +[proposal template](../../templates/contributor-proposal.md). + +## Review Process + +Notify mentors in the designated channel when your proposal is ready for review. +Respond to feedback, ask clarifying questions, and allow time for replies. Show +engagement through thoughtful discussion, useful progress updates, support for +peers, and follow-through on agreed tasks. The recommended internal rubric gives +community engagement 50% of the assessment and technical understanding and +planning the other 50%. + + + +## After Selection: Work with Your Mentor + +Agree on weekly objectives, check-in times, reporting channels, response +windows, and planned absences. Send a brief daily status report on agreed +working days using a shared thread or project log. Include: + +- **Progress:** What I worked on or learned, with links where relevant. +- **Next:** What I plan to do next. +- **Blockers:** What is preventing progress and what help I need. + +Report blockers even when no code was completed, and give early notice of +changes in availability. Ask for help, respond to reviews, and use feedback to +improve your work. Follow the +[Coding Tips](../../../guides/coding-tips/index.md) for readable code, focused +pull requests, testing, and documentation. + +Consult the [GSoC Student Guide](https://google.github.io/gsocguides/student/) +and Google's +[advice for contributors](https://developers.google.com/open-source/gsoc/help/student-advice) +for further application guidance. + +--- + +See the [GSoC guide overview](../contributor/index.md) for all roles. diff --git a/pages/opportunities/gsoc/guides/contributor/index.md b/pages/opportunities/gsoc/guides/contributor/index.md index e9031cd7e..67ca1a477 100644 --- a/pages/opportunities/gsoc/guides/contributor/index.md +++ b/pages/opportunities/gsoc/guides/contributor/index.md @@ -1,101 +1,50 @@ -# Google Summer of Code (GSoC) Contributor Guide +# Google Summer of Code (GSoC) Guides -This guide is intended for both prospective and accepted candidates of the GSoC -program with Open Science Labs. It provides detailed, objective instructions to -help navigate the application process, engage with mentors, and succeed during -the program period. The guide covers project selection, initial contributions, -proposal development, and expectations for approved contributors. +These are Open Science Labs' (OSL) general recommendations for projects and +sub-organizations participating in Google Summer of Code (GSoC) under the OSL +umbrella. Organization admins and maintainers can use, adapt, or incorporate +these recommendations partially or completely into their own project guidelines. +Contributors: also read the guidelines of the project you are contributing to. +Official GSoC rules and applicable codes of conduct still apply. -## Candidates' Guide +Choose the guide for your role. Each page contains the full recommendations for +that role, with links to shared contribution and coding guidance. -This section outlines the steps candidates should follow to apply effectively. +## Organization Admins -### How to Apply +[Read the Organization Admins Guide](../organization-admins/index.md) to +coordinate participation, mentor capacity, selection criteria, engagement +assessment, and evaluation decisions across projects. -#### Selecting a Sub-Organization/Project + -Candidates should begin by reviewing the list of available sub-organizations -under Open Science Labs and their projects. It is important to choose a project -that aligns with individual interests and skills. +## Mentors -#### Initiating Contact with Projects and Mentors +[Read the Mentors Guide](../mentors/index.md) to prepare project guidance, +welcome and assess candidates, publish AI policies, set expectations, and +support contributor progress. -Candidates are advised to contact project mentors using the recommended -communication platform (discord, slack, email, etc). A brief introduction, -expression of interest, and any initial questions about the project or mentoring -process should be included. Each project or sub-organizations should specify the -recommended platform for all the communications with candidates. + -#### Making an Initial Contribution +## Contributor Candidates -Demonstrating commitment early on is valuable. Candidates are encouraged to -contribute a small but meaningful improvement—such as fixing a minor bug or -implementing small features suggested by the mentor. +[Read the Contributor Candidates Guide](../candidates/index.md) to contact the +community, explore the software, write about your experience as a user, and +prepare a proposal. -#### Crafting a Proposal with Mentor Support + -Under mentor guidance, candidates should develop a detailed proposal that -outlines: +For application review, see the +[candidate review process](../candidates/index.md#review-process). -- **Milestones and Timeline:** Specific tasks and expected outcomes within the - program period. -- **Contribution Impact:** How the work will further the project’s goals. -- **Language and Style:** Clear, informative, and objective language; concise - and focused content without unnecessary filler or marketing-style phrasing. + -Candidates should also ensure that proposals do not exhibit signs of complete AI -generation, such as excessive buzzwords or generic phrasing. While AI tools may -be used to enhance clarity, the proposal must reflect the candidate’s own work. +After selection, follow the guidance on +[working with your mentor](../candidates/index.md#after-selection-work-with-your-mentor). -It is essential to review the -[contributor rules](https://summerofcode.withgoogle.com/rules) for the program -and follow the proposal template provided -[here](/opportunities/gsoc/templates/contributor-proposal). +## Shared Guidance -## Review Process - -Mentors will evaluate proposals to determine if candidates meet the fundamental -requirements for effective contribution. Transparent feedback will be provided, -and candidates may be guided to consider alternative projects if a better fit is -identified. When a proposal is ready for review, candidates should send a direct -message to the mentors via the recommended communication channel (e.g., Discord, -Slack, or email). For all other communications, public channels are preferred. -Candidates should remain patient as mentors manage a high volume of messages, -issues, pull requests, and reviews. - -## Approved Contributors - -For accepted candidates, the following guidelines serve as a roadmap for -successful collaboration during the GSoC program with Open Science Labs. - -### Effective Workflow and Proactivity - -- **Establish a Regular Workflow:** Work closely with your mentor to set clear - weekly objectives. -- **Proactive Engagement:** Actively seek tasks, ask clarifying questions, and - schedule regular check-ins to monitor progress. - -### Communication Best Practices - -- **Timely Updates:** Keep mentors informed about progress, challenges, and any - required assistance. -- **Use Designated Channels:** Communicate via the project’s preferred platforms - to ensure transparency and prompt feedback. - -### Programming Best Practices - -- **Adherence to Standards:** Follow the coding standards and best practices - outlined by your mentor and project guidelines. -- **Maintainable Code:** Write clean, well-documented, and maintainable code. -- **Constructive Feedback:** Embrace code reviews as opportunities to learn and - improve your technical skills. - -## Proposal Resources - -Candidates are encouraged to consult the -[GSoC Student Guide](https://google.github.io/gsocguides/student/) for -comprehensive details on the application process and proposal preparation. -Additional recommendations can be found -[here](https://developers.google.com/open-source/gsoc/help/student-advice). For -further guidance, refer to the suggested proposal template available -[here](/opportunities/gsoc/templates/contributor-proposal). +- [Contribution Guidelines](../../../guides/contribution/index.md): community + engagement, task coordination, and reviews. +- [Coding Tips](../../../guides/coding-tips/index.md): readable code, focused + pull requests, tests, documentation, and AI-assisted work. diff --git a/pages/opportunities/gsoc/guides/mentors/index.md b/pages/opportunities/gsoc/guides/mentors/index.md new file mode 100644 index 000000000..d1f4ed328 --- /dev/null +++ b/pages/opportunities/gsoc/guides/mentors/index.md @@ -0,0 +1,116 @@ +# GSoC Guide for Mentors + +These are Open Science Labs' (OSL) general recommendations for projects and +sub-organizations participating in Google Summer of Code (GSoC) under the OSL +umbrella. Organization admins and maintainers can use, adapt, or incorporate +these recommendations partially or completely into their own project guidelines. +Contributors: also read the guidelines of the project you are contributing to. +Official GSoC rules and applicable codes of conduct still apply. + +## Prepare the Project and Welcome Candidates + +Publish the preferred community app or communication channel, contact details, +and expected response times alongside the project idea. Explain the project's +mission, intended users, main workflows, and development setup. State which +ideas are planned for the upcoming GSoC edition and update candidates when plans +change. + +Provide a manageable starting workflow and examples of helpful contributions, +including documentation, tests, and bug fixes. Encourage candidates to spend +several days using the software before rushing into a pull request. For a tool +or library, suggest different use cases and realistic tasks so candidates can +understand both its strengths and its limitations. + +## Use a Project Experience Report as the First Contribution + +Ask candidates to write a blog post or newcomer experience report from a user's +perspective. Use it as an initial selection criterion and announce the expected +effort, deadline, submission channel, and assessment criteria in advance. + +Assess what the candidate tried, how clearly they explain the software, what +they learned, and the usefulness of their observations. Value reproducible +examples and constructive suggestions. Accept a Markdown document or draft +shared with the team without requiring a personal blog or a pull request. If +setup fails, review the steps attempted and the blocker, and help the candidate +move forward. + +Keep the task manageable and give candidates time to explore. Do not require a +long history of contributions; use the activity to help newcomers develop and +demonstrate understanding. + +## Publish a Project Selection Checklist + +Align project criteria with the +[organization's selection framework](../organization-admins/index.md#publish-the-selection-framework). +For example: + +- [ ] The applicant meets the current official GSoC eligibility requirements. +- [ ] The project experience report meets the published criteria. +- [ ] The proposal explains the project's goals and includes the requested + sections. +- [ ] The candidate follows the published AI-use and disclosure policy. +- [ ] The candidate shows meaningful engagement and responds within agreed + windows. +- [ ] Availability and proposed scope are realistic for the project. + +Include a small, explicit, project-relevant instruction to check that candidates +read the guidance. Request a "Newcomer insight" proposal section with one +observation from trying the software. Include it in the instructions and +checklist, and explain how omissions are handled. Use the response to discuss +the candidate's experience and understanding. + +## Make the AI Policy Specific + +Explain permitted and prohibited uses separately for proposals, experience +reports, code, tests, and documentation. State whether editing, translation, +brainstorming, or code generation is allowed; what tools or data restrictions +apply; and how assistance must be disclosed. Link the policy from the project +idea, proposal instructions, and contribution guide. + +Assess understanding through the work and discussion. Describe how suspected +violations will be reviewed and let candidates explain their work. Writing style +alone is not evidence of AI use. + +## Review Proposals and Agree on Expectations + +Assess proposals using the published checklist and +[assessment rubric](../organization-admins/index.md#give-community-engagement-explicit-weight). +Provide clear feedback and discuss alternatives when another project is a better +fit. Look for thoughtful questions, responses to feedback, useful observations +from using the software, and follow-through on agreed tasks. + +Share a contributor checklist before selection covering deliverables, reporting +frequency, response windows, check-ins, AI policy, review participation, and +evaluation criteria. State your own availability, review turnaround, and backup +contact. Explain what happens when expectations are repeatedly unmet. + +Confirm the working agreement during community bonding, including time zones, +planned absences, and any adjustments. Keep a shared record of changes. + +## Support Progress and Address Problems Early + +Set clear weekly objectives, hold regular check-ins, and review daily status +reports on agreed working days. Respond to requests for help and give actionable +feedback. During selection, announce any reporting exercise in advance and limit +it to a short, defined activity. + +If progress or engagement falls short, discuss specific examples privately, +identify blockers and gaps in mentoring support, and agree on next steps and a +review date. Distinguish persistent failure to follow through from an agreed +absence or a technical obstacle raised promptly. + +Decline candidates who do not meet published selection criteria. During the +program, give an honest failing evaluation when agreed expectations remain +unmet; passing someone solely to avoid a difficult conversation helps neither +the contributor nor the project. Coordinate with organization admins, document +the basis for the decision, and follow the current GSoC evaluation process. +Communicate concerns early and provide feedback before the evaluation. + +For official mentoring guidance, see +[Setting Expectations](https://google.github.io/gsocguides/mentor/setting-expectations), +[Selecting a Contributor](https://google.github.io/gsocguides/mentor/selecting-a-student), +and [Evaluations](https://google.github.io/gsocguides/mentor/evaluations). + +--- + +See the [GSoC guide overview](../contributor/index.md) for all roles. diff --git a/pages/opportunities/gsoc/guides/organization-admins/index.md b/pages/opportunities/gsoc/guides/organization-admins/index.md new file mode 100644 index 000000000..f82a35d28 --- /dev/null +++ b/pages/opportunities/gsoc/guides/organization-admins/index.md @@ -0,0 +1,75 @@ +# GSoC Guide for Organization Admins + +These are Open Science Labs' (OSL) general recommendations for projects and +sub-organizations participating in Google Summer of Code (GSoC) under the OSL +umbrella. Organization admins and maintainers can use, adapt, or incorporate +these recommendations partially or completely into their own project guidelines. +Contributors: also read the guidelines of the project you are contributing to. +Official GSoC rules and applicable codes of conduct still apply. + +## Coordinate Participation and Mentor Capacity + +Confirm which affiliated projects intend to participate in the upcoming GSoC +edition and which project ideas they plan to submit. Distinguish planned +participation from confirmed participation when communicating with candidates. +Keep project ideas, contacts, and participation updates easy to find. + +Confirm mentor availability and backup coverage before offering project ideas. +Balance contributor allocations across projects and mentors, and keep the scope +within the mentoring capacity available. Do not promise candidates a place +before selection and slot allocation are complete. + +Publish the organization contact channel, selection timeline, and escalation +route for candidates and mentors. Use OSL's coordination channels for matters +across projects and each project's preferred community channel for its work. + +## Publish the Selection Framework + +Publish common selection criteria, the assessment rubric, and evaluation +expectations **before the selection period begins**. Coordinate with mentors to +make project-specific criteria equally clear. Separate minimum requirements that +exclude an application from scored preferences used to compare suitable +candidates. + +For each minimum requirement, state the evidence, deadline, whether correction +or clarification is possible, and how unmet criteria affect selection. Use the +same published criteria consistently, record selection reasons, and account for +agreed accessibility or scheduling accommodations. Meeting the checklist does +not guarantee a slot. Review the current +[official GSoC rules](https://summerofcode.withgoogle.com/rules) when defining +eligibility and selection procedures. + +## Give Community Engagement Explicit Weight + +Assign **50% of the internal assessment to community engagement**. Use the +remaining 50% to assess technical understanding and planning during selection, +and agreed deliverables and code quality during the program. Publish the rubric, +evidence, and minimum thresholds for both areas. For example: + +| Area | Weight | Evidence to consider | +| ------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | +| Communication and reliability | 20% | Useful updates, timely replies within agreed windows, and early notice of blockers or absences. | +| Collaboration and response to feedback | 20% | Constructive discussion, follow-through on review, and support for peers where opportunities arise. | +| Learning and sharing project understanding | 10% | User experience reports, documentation, or explanations that help others learn. | +| Technical understanding and project work | 50% | A feasible proposal during selection; tested, documented progress against agreed goals during the program. | + +Assess observable behavior rather than personality, English fluency, message +volume, or constant availability. Give newcomers a reasonable opportunity to +demonstrate each criterion. A strong engagement score does not remove the need +to meet agreed technical goals. Use this rubric for internal assessment +alongside the official GSoC evaluation requirements. + +## Support Consistent Decisions and Resolve Problems + +Check that mentors publish their expectations before selection, provide timely +feedback, and have enough capacity to support their contributors. Arrange backup +support when a mentor is unavailable. + +Review concerns and evaluation decisions with mentors, including evidence of +missed expectations, support provided, and feedback shared with the contributor. +Address gaps in mentoring support as well as contributor engagement. Follow the +current GSoC evaluation process and communicate decisions clearly. + +--- + +See the [GSoC guide overview](../contributor/index.md) for all roles. diff --git a/pages/opportunities/gsoc/index.md b/pages/opportunities/gsoc/index.md index ef9979c2f..f3c4d044c 100644 --- a/pages/opportunities/gsoc/index.md +++ b/pages/opportunities/gsoc/index.md @@ -44,21 +44,27 @@ project by email to by January 31, 2026. Check out our project idea template for more insights: . -Additionally, all discussions about OSL participation in GSoC will happen on our -Discord server at . +Read the GSoC guides for +[organization admins](guides/organization-admins/index.md) and +[mentors](guides/mentors/index.md) to prepare participation, selection, and +mentoring. + +Use OSL's Discord server at for +coordination across projects. Use each project's preferred community channel for +its ideas, onboarding, and technical discussions. ### For Potential Contributors If you're a student or a newcomer eager to get involved in open source through GSoC, stay tuned to this page for updates on project ideas and submission guidelines. Check out our -[Contributor Guide](/opportunities/gsoc/guides/contributor) for more details on -how to prepare for your application and stay updated with our project idea pages -to check which projects are applying with us to GSoC. +[GSoC Guide for Contributor Candidates](guides/candidates/index.md) for more +details on how to prepare for your application and stay updated with our project +idea pages to check which projects are applying with us to GSoC. ### Reach Out for More Information For any inquiries or to discuss project ideas, feel free to reach out at `team@opensciencelabs.org`. Also, join us on our Discord server at -, where all discussions with mentors and -contributors will take place. + for OSL-wide questions. Contact project +mentors and contributors through their project's preferred community channel. diff --git a/pages/opportunities/guides/coding-tips/index.md b/pages/opportunities/guides/coding-tips/index.md new file mode 100644 index 000000000..fea58425f --- /dev/null +++ b/pages/opportunities/guides/coding-tips/index.md @@ -0,0 +1,127 @@ +--- +title: "Coding Tips" +description: + "Practical coding recommendations that OSL-affiliated projects and GSoC + sub-organizations can adopt or adapt." +date: "2026-10-31" +authors: ["OSL Team"] +template: single-sidebar.html +--- + +# Coding Tips + +These are Open Science Labs' (OSL) general coding recommendations for affiliated +projects, including sub-organizations participating in GSoC under the OSL +umbrella. Maintainers can use, adapt, or incorporate these recommendations +partially or completely into their own project guidelines. Contributors: also +read the guidelines of the project you are contributing to. + +For collaboration and mentoring suggestions, see our +[Contribution Guidelines](../contribution/index.md). This page focuses on the +technical side of a contribution. + +## Start with the Project's Workflow + +- Read `CONTRIBUTING.md`, the development documentation, and nearby code before + editing. Use the project's existing patterns and tools. +- Set up the documented development environment and install dependencies using + the project's configuration or lock files. An isolated environment helps avoid + conflicts with other projects and makes problems easier to reproduce. +- Run the relevant checks before changing code so you can distinguish existing + failures from those introduced by your work. +- Reuse the project's commands for testing, formatting, and documentation. + Document and automate recurring commands to make onboarding easier. + +## Keep Changes Small and Focused + +- Aim for one clear purpose per pull request. Separate unrelated cleanup, + formatting, dependency updates, and new features when practical. +- Discuss large features or refactoring with maintainers before implementation. + Agree on smaller steps that can each be reviewed and checked. +- Use pull request size guidelines as a review aid and explain exceptions. + Account for generated files and related tests when assessing size; consider + complexity and scope alongside line count. +- Follow the project's preferred way of updating branches, whether that is a + merge or a rebase. Coordinate before rewriting a branch others use. + +## Write Readable Code + +- Use descriptive names and keep functions focused on a clear responsibility. + Prefer straightforward code over unnecessary abstractions. +- Reduce deep nesting where it helps readability, for example with guard clauses + or small helper functions. At around four levels, review the structure for + opportunities to simplify it. +- Keep comments that explain intent, constraints, scientific assumptions, or + non-obvious decisions. Remove outdated comments and those that only repeat the + code. Clear comments and documentation are valuable even when code is + readable. +- Keep comments professional and consistent with project style; avoid decorative + emojis unless the project uses them for a specific purpose. +- Use the project's formatter and whitespace conventions. End text files with a + newline; this does not require adding an extra blank line. + +## Use Automated Checks Where Available + +If the project uses `pre-commit`, install its configured hooks in your local +checkout and run them before requesting review: + +```bash +pre-commit install +pre-commit run --all-files +``` + +Install the development dependencies first. These commands use the repository's +`pre-commit` configuration. Inspect automatic changes and include only those +relevant to your contribution. + +Run the checks appropriate to the change, such as formatting, linting, type +checking, or documentation builds. Review continuous integration (CI) results +and investigate failures. If a check cannot run locally, explain the limitation +in the pull request so reviewers know what remains unverified. + +## Test Behavior and Update Documentation + +- For a bug fix, add a regression test that demonstrates the problem and passes + with the fix when practical. +- For new behavior, cover expected use, relevant edge cases, and failure cases. + Use the project's existing testing framework and conventions. +- Keep tests reproducible. Use small fixtures and control randomness, external + services, or other sources of variability where appropriate. +- Update examples, API documentation, or setup instructions when the change + affects them. For scientific code, document assumptions and validate results + against suitable reference cases. +- Describe how you checked the change, including commands and results, in the + pull request. Passing CI supports review but does not replace understanding + the code or checking that it solves the intended problem. + +## Use AI Tools Responsibly + +Maintainers: publish an AI-use policy in the contribution guide. State which +activities allow AI assistance, which uses are prohibited, and what disclosure +is expected. + +Contributors: follow the AI-use policy and understand and verify every submitted +change. Check APIs, dependencies, tests, and explanations rather than assuming +generated output is correct. Remove irrelevant code and comments, respect +confidentiality and licensing obligations, and follow the project's disclosure +policy. Contributors remain responsible for explaining and maintaining their +work. Review the substance of a contribution; writing style or emojis alone do +not establish whether AI was used. + +## Before Requesting Review + +- Read your own diff and remove accidental or unrelated changes. +- Summarize the problem, approach, and any tradeoffs; link related issues. +- Include test results, documentation updates, and any known limitations. +- Keep unfinished work in draft when the platform supports it, and use the + project's agreed channel when it is ready for review. + +## Learn More from the OSL Blog + +- [First Time Contributors](../../../blog/first-time-contributors/index.md): + development environments, documentation, testing, and contribution workflows. +- [Three Years with Google Summer of Code: What I've Learned](../../../blog/three-years-with-google-summer-of-code-what-ive-learned/index.md): + small pull requests, early design discussions, and learning through mentoring. +- [Streamlining Project Automation with Makim](../../../blog/streamlining-project-automation-with-makim/index.md): + an example of organizing repeatable project tasks. Follow your project's + current setup instructions when applying ideas from older tutorials. diff --git a/pages/opportunities/guides/contribution/index.md b/pages/opportunities/guides/contribution/index.md index 99b08085e..9ca61bc2a 100644 --- a/pages/opportunities/guides/contribution/index.md +++ b/pages/opportunities/guides/contribution/index.md @@ -1,6 +1,8 @@ --- title: "Contribution Guidelines" -description: "Contribution Guidelines" +description: + "Adaptable contribution recommendations for OSL-affiliated projects and GSoC + sub-organizations." date: "2025-03-23" authors: ["OSL Team"] template: single-sidebar.html @@ -8,63 +10,106 @@ template: single-sidebar.html # Contribution Guidelines -These recommendations are general guidelines from Open Science Labs. Each -project may have its own specific set of recommendations and rules; contributors -should review those for each project. +These are Open Science Labs' (OSL) general recommendations for affiliated +projects, including sub-organizations participating in Google Summer of Code +(GSoC) under the OSL umbrella. Maintainers can use, adapt, or incorporate these +recommendations partially or completely into their own project guidelines. +Contributors: also read the guidelines of the project you are contributing to. +Applicable codes of conduct and official program rules still apply. + +## Prepare Contribution Resources + +Publish a `CONTRIBUTING.md` file and issue or pull request templates covering: + +- Where to ask questions, discuss ideas, and request reviews. +- How to set up the development environment and choose a first task. +- Which coding, testing, documentation, and AI-use policies the project follows. +- How reviews work, including expected response times and how inactive work is + handled. +- How GSoC contributors and mentors will share progress and arrange check-ins. + +Link these resources from the project idea page and onboarding materials. If +expectations change, explain the change to contributors and give them time to +adapt. Include the technical practices described in +[Coding Tips](../coding-tips/index.md) in your onboarding resources. ## Community Engagement -- **Communication Platforms:** Each project may use its preferred communication - platform for discussions, such as code repository platforms (GitHub, GitLab, - etc.) or chat-based platforms (Discord, Slack, etc.). Contributors should - verify with the community and mentors which platform is recommended for - seeking assistance, discussing ideas, and requesting reviews. +- **Communication Platforms:** Choose clear channels for discussions, help, and + review requests, such as GitHub, GitLab, Discord, or Slack. Explain the + purpose of each channel. Keep technical discussions public so others can + learn; use private channels for sensitive matters. + +- **Collaboration and Support:** Help others when possible. Share what you learn + and support fellow contributors as they develop their skills. -- **Collaboration and Support:** Contributors are encouraged to assist others - when possible, as everyone is here to learn and support one another. +- **Respect and Inclusivity:** Communicate with kindness and respect, + particularly with beginners and colleagues for whom English is not their first + language. Give constructive feedback and encouragement that helps others + develop their language and technical skills. -- **Respect and Inclusivity:** Contributors should communicate with kindness and - respect, particularly when interacting with beginners or colleagues for whom - English may not be their first language. Instead of engaging in arguments, - they should offer constructive feedback and encouragement to help others - improve both their language and technical skills. +- **Channel Usage:** Share links to issues and pull requests in the coordination + channel when discussion or review is needed. Discuss substantial work before + implementation, and record decisions in the relevant issue or pull request. -- **Channel Usage:** If the primary discussion channel is not the code - repository platform, contributors should use the designated platform to draw - attention to pull requests or issues. Initiating a discussion there prior to - opening issues or pull requests is also expected. +- **Mentoring and Progress:** For GSoC, agree on realistic check-in times, + progress updates, and a way to raise blockers. Hold short regular meetings and + record next steps. Account for time zones, accessibility needs, and mentor + availability when setting the routine. ## Contributions -- **Task Coordination:** Contributors should avoid duplicating work by verifying - whether someone else is already addressing a task or if the task remains - relevant before beginning work. +- **Task Coordination:** Before starting, check whether a task is still relevant + and whether someone is already working on it. Comment on the issue or use the + coordination channel. Maintainers: provide small starter tasks and examples of + helpful contributions, including documentation and tests. + +- **Discussing Larger Changes:** Propose substantial features, architectural + changes, or broad refactoring before implementation. Agree on scope with + maintainers and split the work into focused pull requests where practical. -- **Managing Stale Contributions:** Project maintainers may implement mechanisms - to label and close stale issues and pull requests. Some contributors open pull - requests without following up or addressing review recommendations, which can - impede progress. +- **Preparing for Review:** Explain the problem, proposed change, and validation + in your pull request. Link related issues, use the pull request template, and + describe remaining questions. Keep unfinished work in draft and mark it ready + when it is prepared for review. -- **Branch Management:** When updating a branch, contributors should follow the - project's preferred approach, whether that involves using a **rebase** or a - **merge commit**. +- **Reviewing Together:** Treat review as a chance to learn. Respond to feedback + and explain tradeoffs. As a reviewer, distinguish required changes from + suggestions and explain your reasoning. Allow time for replies before + following up through the agreed channel. -- If your PR is not ready yet for review, please keep it in **draft mode**. +- **Managing Inactive Work:** Publish a process and timeframes for labeling, + returning to draft, or closing inactive issues and pull requests. Check in + with the contributor before taking action and explain how work can resume. + Account for contributor circumstances and delays in mentor or maintainer + feedback. + +- **Branch Management:** Document whether branch updates use a **rebase** or a + **merge commit**, and use that approach consistently. ## Coding Tips -- Ensure that `pre-commit` is applied to your branch before opening a pull - request. Run `pre-commit install` to enable pre-commit hooks, ensuring they - are applied automatically before every commit. -- Avoid excessive nesting. Try to keep nesting levels to **four or fewer** for - better readability and maintainability. -- Follow the project's specific coding guidelines. Review them regularly to - ensure consistency across contributions. -- Remove any unnecessary comments. In most cases, if you need to explain what - your code does, it may indicate that the code is unclear or overly complex. - This is also often a sign of code generated by Generative AI. -- Do not use emojis in comments. This is typically seen as a red flag and may - suggest improper use of AI-generated content. -- Ensure there is an empty line at the end of each file. GitHub highlights - missing end-of-file newlines with a red icon. Configure your IDE to - automatically add this final newline. +Technical recommendations now have their own +[Coding Tips](../coding-tips/index.md) page. It covers readable code, +development environments, automated checks, testing, documentation, and +responsible use of AI tools. + +## GSoC Selection and Mentoring + +Read the recommendations for your role in the GSoC guide: + +- [Organization Admins](../../gsoc/guides/organization-admins/index.md): + coordinate participation, mentor capacity, selection criteria, and + evaluations. +- [Mentors](../../gsoc/guides/mentors/index.md): prepare project guidance, + review candidates, and support contributor progress. +- [Contributor Candidates](../../gsoc/guides/candidates/index.md): contact the + community, explore the software, write about your experience, and prepare an + application. + +## Further Guidance + +- [GSoC Guides Overview](../../gsoc/guides/contributor/index.md): + recommendations for organization admins, mentors, and contributor candidates. +- [Three Years with Google Summer of Code: What I've Learned](../../../blog/three-years-with-google-summer-of-code-what-ive-learned/index.md): + OSL's experience with mentoring, communication, and manageable contributions.