From 558018267bad45180ab1c1d57a76d7273e432da0 Mon Sep 17 00:00:00 2001 From: Ivan Ogasawara Date: Sat, 31 Oct 2026 08:58:41 -0400 Subject: [PATCH 1/5] docs: clarify contribution recommendations and add coding tips --- mkdocs.yml | 1 + .../gsoc/guides/contributor/index.md | 11 ++ .../opportunities/guides/coding-tips/index.md | 129 ++++++++++++++++++ .../guides/contribution/index.md | 117 +++++++++++----- 4 files changed, 221 insertions(+), 37 deletions(-) create mode 100644 pages/opportunities/guides/coding-tips/index.md diff --git a/mkdocs.yml b/mkdocs.yml index 19489f0a1..bd8ca56c4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -68,6 +68,7 @@ nav: - Overview: "opportunities/gsoc/index.md" - Project Ideas: "opportunities/gsoc/project-ideas/index.md" - "Contribution Guidelines": "opportunities/guides/contribution/index.md" + - "Coding Tips": "opportunities/guides/coding-tips/index.md" - "Candidates' Guide": "opportunities/gsoc/guides/contributor/index.md" - "Template: Project Idea": "opportunities/gsoc/templates/project-ideas.md" - "Template: Candidates Project Proposal": "opportunities/gsoc/templates/contributor-proposal.md" diff --git a/pages/opportunities/gsoc/guides/contributor/index.md b/pages/opportunities/gsoc/guides/contributor/index.md index e9031cd7e..63495e7c9 100644 --- a/pages/opportunities/gsoc/guides/contributor/index.md +++ b/pages/opportunities/gsoc/guides/contributor/index.md @@ -6,6 +6,12 @@ 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. +Affiliated projects and sub-organizations may adopt, partially use, or adapt +OSL's [Contribution Guidelines](../../../guides/contribution/index.md) and +[Coding Tips](../../../guides/coding-tips/index.md). These are recommendations; +check your project's own guidance to understand which practices it follows. +Official GSoC rules and applicable codes of conduct still apply. + ## Candidates' Guide This section outlines the steps candidates should follow to apply effectively. @@ -84,6 +90,11 @@ successful collaboration during the GSoC program with Open Science Labs. ### Programming Best Practices +For practical suggestions on code readability, focused pull requests, testing, +and AI-assisted work, see OSL's +[Coding Tips](../../../guides/coding-tips/index.md). Use them alongside the +practices adopted by your project and agreed with your mentor. + - **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. diff --git a/pages/opportunities/guides/coding-tips/index.md b/pages/opportunities/guides/coding-tips/index.md new file mode 100644 index 000000000..9203ffafc --- /dev/null +++ b/pages/opportunities/guides/coding-tips/index.md @@ -0,0 +1,129 @@ +--- +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 + +Open Science Labs (OSL) shares these recommendations with affiliated projects, +including sub-organizations participating in GSoC with us. Projects may follow +them completely, select the parts that help, or adapt them to their language, +tooling, and community. Contributors should follow the practices their project +has adopted and ask maintainers when something is unclear. + +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. + Projects can document or automate these commands to make onboarding easier; + adopting a particular automation tool is optional. + +## 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. +- If a project chooses a pull request size guideline, treat it as a review aid + and explain exceptions. Generated files and related tests may affect the size; + line count alone does not determine whether a change is manageable. +- 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. Around four levels can be a useful prompt to + reconsider the structure, rather than a universal limit. +- 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 +``` + +Use the project's installation instructions first. These commands apply to +projects with a `pre-commit` configuration; other projects may provide different +checks. Inspect any 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 + +Projects can decide whether AI-assisted contributions are allowed and under +which conditions. Maintainers can publish that policy in their contribution +guide, including any disclosure expectations. + +Where use is allowed, 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..34ef72d5c 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,17 +10,42 @@ 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. +Open Science Labs (OSL) offers this guide to affiliated projects and +sub-organizations participating in Google Summer of Code (GSoC) with us. It is a +starting point for building a welcoming, sustainable contribution process. +Projects can adopt it in full, use selected recommendations, or adapt it to +their community, tools, and mentoring capacity. It can also support projects in +other OSL contribution and internship initiatives. + +These recommendations are optional; they do not establish a single workflow for +every project. Contributors should read their project's own contribution guide +and ask maintainers which practices apply. Applicable codes of conduct and +official program rules still apply independently of this guide. + +## Adapting This Guide for Your Project + +Maintainers and mentors may find it useful to 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. Our separate [Coding Tips](../coding-tips/index.md) page offers technical +practices projects can select or adapt alongside this guide. ## 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:** Projects can choose the platforms that work for + their community, such as GitHub, GitLab, Discord, or Slack. Publish where + contributors can seek help, discuss ideas, and request reviews. Public + discussions help others learn; private channels are appropriate for sensitive + matters or when the project's process calls for them. - **Collaboration and Support:** Contributors are encouraged to assist others when possible, as everyone is here to learn and support one another. @@ -29,42 +56,58 @@ should review those for each project. they should offer constructive feedback and encouragement to help others improve both their language and technical skills. -- **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. +- **Channel Usage:** If a project coordinates in chat, contributors can share + links to relevant issues or pull requests there. Projects may prefer a + discussion before substantial work begins; make that preference clear without + requiring a separate chat discussion for every small contribution. + +- **Mentoring and Progress:** For GSoC, agree on realistic check-in times, + progress updates, and a way to raise blockers. Short regular meetings and + written next steps can help. Consider time zones, accessibility needs, and + mentor availability when choosing a 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 + project's preferred channel to coordinate. Maintainers can offer small starter + tasks and examples of helpful contributions, including documentation and + tests. -- **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. +- **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. + +- **Preparing for Review:** A useful pull request explains the problem, the + proposed change, and how it was checked. Link related issues, follow the + project's templates, and describe any remaining questions. Draft mode is + helpful for work in progress; mark it ready when it meets the project's review + expectations. + +- **Reviewing Together:** Treat review as a chance to learn. Contributors can + respond to feedback and explain tradeoffs; reviewers can distinguish required + changes from suggestions and explain their reasoning. Allow time for replies + before following up through the agreed channel. + +- **Managing Inactive Work:** Projects may choose to label, return to draft, or + close inactive issues and pull requests. Publish any timeframes, check in with + the contributor first, and explain how work can resume. Consider both + contributor circumstances and delays in mentor or maintainer feedback. - **Branch Management:** When updating a branch, contributors should follow the project's preferred approach, whether that involves using a **rebase** or a **merge commit**. -- If your PR is not ready yet for review, please keep it in **draft mode**. - ## 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. + +## Further Guidance + +- [GSoC Contributor Guide](../../gsoc/guides/contributor/index.md): preparing an + application and working with mentors. +- [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. From db61b7d80f99a68f0fd386703b88e0824a5f356a Mon Sep 17 00:00:00 2001 From: Ivan Ogasawara Date: Sat, 31 Oct 2026 09:41:00 -0400 Subject: [PATCH 2/5] docs: suggest GSoC selection and engagement practices --- .../gsoc/guides/contributor/index.md | 174 +++++++++++++++++- .../opportunities/guides/coding-tips/index.md | 4 +- .../guides/contribution/index.md | 20 +- 3 files changed, 182 insertions(+), 16 deletions(-) diff --git a/pages/opportunities/gsoc/guides/contributor/index.md b/pages/opportunities/gsoc/guides/contributor/index.md index 63495e7c9..888fe556f 100644 --- a/pages/opportunities/gsoc/guides/contributor/index.md +++ b/pages/opportunities/gsoc/guides/contributor/index.md @@ -4,13 +4,16 @@ 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. +proposal development, and expectations for approved contributors. It also +includes +[suggested practices for mentors and sub-organizations](#suggested-practices-for-mentors-and-sub-organizations) +on publishing criteria, assessing engagement, and supporting contributors. Affiliated projects and sub-organizations may adopt, partially use, or adapt OSL's [Contribution Guidelines](../../../guides/contribution/index.md) and -[Coding Tips](../../../guides/coding-tips/index.md). These are recommendations; -check your project's own guidance to understand which practices it follows. -Official GSoC rules and applicable codes of conduct still apply. +[Coding Tips](../../../guides/coding-tips/index.md). These are OSL's suggestions +for practices; check your project's own guidance to understand which practices +it follows. Official GSoC rules and applicable codes of conduct still apply. ## Candidates' Guide @@ -34,9 +37,28 @@ recommended platform for all the communications with candidates. #### Making an Initial Contribution -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. +An initial contribution can demonstrate understanding of the project before any +code or pull request. A project may ask candidates to try a small, documented +workflow and write a short blog-style introduction or newcomer experience report +covering: + +- The project's mission, main objectives, and intended users. +- How to install or access it and complete one useful example, with reproducible + instructions for other newcomers. +- What works well, what was confusing, and any setup or documentation obstacles. +- Constructive suggestions for improvement and what the candidate learned. + +The project can use this as an initial selection criterion, provided it +announces the task, expected effort, deadline, and assessment criteria in +advance. A Markdown document or draft shared with mentors can be enough; a +personal blog, public publication, and a pull request need not be prerequisites. +If setup fails, documenting the steps tried and the blocker can still provide +useful evidence. + +Candidates can then agree on a small follow-up contribution, such as improving +onboarding documentation, adding a test, or fixing a bug. Follow the project's +published sequence rather than assuming that opening many pull requests improves +selection chances. #### Crafting a Proposal with Mentor Support @@ -49,9 +71,17 @@ outlines: - **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. +Read the project's AI-use policy before preparing the proposal or introductory +report. It should explain whether AI assistance is allowed, for which +activities, and what disclosure is expected. The submission should reflect the +candidate's own understanding; candidates should be able to explain and verify +everything they submit. Ask mentors if the policy is unclear. Writing style +alone is not evidence of AI use. + +Also check for project-specific proposal instructions. For example, a project +may ask for a short "Newcomer insight" section describing an onboarding obstacle +and one suggested improvement. Include the requested material so reviewers can +assess both your understanding and your attention to the project instructions. It is essential to review the [contributor rules](https://summerofcode.withgoogle.com/rules) for the program @@ -60,6 +90,21 @@ and follow the proposal template provided ## Review Process +Projects may publish a selection checklist with minimum criteria and a separate +scoring rubric. Read both before applying. Minimum criteria may cover the +introductory report, required proposal sections, AI-policy compliance, agreed +availability, and evidence of engagement. Projects should distinguish missing +requirements that make an application ineligible for their selection process +from preferences used to compare otherwise suitable candidates. + +Engagement can include asking thoughtful questions, responding to feedback, +sharing progress, helping others when appropriate, and following through on +agreed tasks. Quality and reliability matter more than message counts, constant +online presence, or the number of pull requests. A project may choose a rubric +with **50% community engagement and 50% technical understanding and project +planning**. This is a suggested project rubric; projects can adapt its weights +and criteria to their context. + 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 @@ -88,6 +133,21 @@ successful collaboration during the GSoC program with Open Science Labs. - **Use Designated Channels:** Communicate via the project’s preferred platforms to ensure transparency and prompt feedback. +A project may ask for a brief daily status report to the mentor on agreed +working days. Agree on the channel and delivery window, accounting for time +zones and planned absences. A shared thread or project log can avoid repeated +direct messages and let other mentors help. A useful format is: + +- **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. + +Reporting a blocker is useful even when no code was completed. Mentors should +review updates and respond to requests for help. Daily reporting supports +coordination; it is not a requirement to be online continuously or work every +calendar day. During selection, any reporting exercise should be announced in +advance and limited to a short, defined activity. + ### Programming Best Practices For practical suggestions on code readability, focused pull requests, testing, @@ -101,6 +161,100 @@ practices adopted by your project and agreed with your mentor. - **Constructive Feedback:** Embrace code reviews as opportunities to learn and improve your technical skills. +## Suggested Practices for Mentors and Sub-Organizations + +OSL suggests the following practices. Each project can follow them in full, +select the parts that help, or adapt them to its context, and should explain its +choices to candidates **before the selection period begins**. Confirm the +working agreement with selected contributors during community bonding, including +any agreed adjustments. + +### Publish a Selection Checklist + +Separate minimum requirements from scored preferences. For each minimum, state +what evidence is expected, the deadline, whether clarification or correction is +possible, and when failure to meet it excludes an application. For example: + +- [ ] The applicant meets the current official GSoC eligibility requirements. +- [ ] The introductory project-use report meets the published criteria. +- [ ] The proposal includes the requested sections and demonstrates + understanding of the project's goals. +- [ ] The candidate follows the published AI-use and disclosure policy. +- [ ] The candidate shows meaningful engagement and responds within agreed + communication windows. +- [ ] Availability and proposed scope are realistic for the project. + +Use the same published criteria consistently, document selection reasons, and +allow agreed accessibility or scheduling accommodations. Meeting the checklist +does not guarantee a slot. Additional project criteria are separate from +[Google's official rules](https://summerofcode.withgoogle.com/rules). + +### Check That Instructions Were Read + +A small, explicit, project-relevant instruction can help assess whether a +candidate read the guidance. For example, request a "Newcomer insight" section +with one observation from trying the project. Include it in the proposal +instructions and checklist, and explain how omissions are handled. Prefer a +useful task over an unrelated secret phrase or personal trivia; it gives mentors +evidence they can discuss with the candidate. + +### Make the AI Policy Specific + +Explain permitted and prohibited uses separately for proposals, introductory +reports, code, tests, and documentation. State whether editing, translation, +brainstorming, or code generation is allowed; what tools or data restrictions +apply; and how assistance should be disclosed. Describe how suspected violations +will be reviewed and let candidates explain their work. Link the policy from the +project idea, proposal instructions, and contribution guide. Do not assume every +OSL-affiliated project uses the same policy. + +### Give Community Engagement Explicit Weight + +Projects may choose to assign **50% of their internal assessment to community +engagement**. The remaining 50% can assess technical understanding and planning +during selection, or agreed deliverables and code quality during the program. +Publish the rubric, evidence, and any 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% | Newcomer insights, 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. This example is not Google's evaluation formula +and does not replace official GSoC evaluation requirements. + +### Set Expectations and Address Problems Early + +Share a contributor checklist before selection covering deliverables, reporting +frequency, response windows, check-ins, AI policy, review participation, and +evaluation criteria. Explain what happens when expectations are repeatedly +unmet. Also state mentor responsibilities, including availability, review +turnaround, and a backup contact. Keep a shared record of agreed changes. + +If progress or engagement falls short, discuss specific examples privately, +identify blockers and any gaps in mentoring support, and agree on concrete next +steps and a review date. Distinguish persistent failure to follow through from +an agreed absence or a technical obstacle raised promptly. + +It is appropriate to decline candidates who do not meet published selection +criteria. During the program, mentors should 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 OSL's organization administrators, document the basis for the decision, and +follow the current GSoC evaluation process. Concerns should be communicated +early so the evaluation is not the first notice of a problem. + +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). + ## Proposal Resources Candidates are encouraged to consult the diff --git a/pages/opportunities/guides/coding-tips/index.md b/pages/opportunities/guides/coding-tips/index.md index 9203ffafc..78ba16b9f 100644 --- a/pages/opportunities/guides/coding-tips/index.md +++ b/pages/opportunities/guides/coding-tips/index.md @@ -30,8 +30,8 @@ technical side of a contribution. - 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. - Projects can document or automate these commands to make onboarding easier; - adopting a particular automation tool is optional. + Projects can document or automate these commands to make onboarding easier and + choose the tools that fit their workflow. ## Keep Changes Small and Focused diff --git a/pages/opportunities/guides/contribution/index.md b/pages/opportunities/guides/contribution/index.md index 34ef72d5c..dcb2a8b71 100644 --- a/pages/opportunities/guides/contribution/index.md +++ b/pages/opportunities/guides/contribution/index.md @@ -17,10 +17,11 @@ Projects can adopt it in full, use selected recommendations, or adapt it to their community, tools, and mentoring capacity. It can also support projects in other OSL contribution and internship initiatives. -These recommendations are optional; they do not establish a single workflow for -every project. Contributors should read their project's own contribution guide -and ask maintainers which practices apply. Applicable codes of conduct and -official program rules still apply independently of this guide. +These are OSL's suggestions for contribution practices. Each project can choose +which suggestions to follow or adapt. Contributors should read their project's +own contribution guide and ask maintainers which practices apply. Applicable +codes of conduct and official program rules still apply independently of this +guide. ## Adapting This Guide for Your Project @@ -105,6 +106,17 @@ Technical recommendations now have their own development environments, automated checks, testing, documentation, and responsible use of AI tools. +## GSoC Selection and Mentoring + +Projects participating in GSoC with OSL can use the +[suggested practices for mentors and sub-organizations](../../gsoc/guides/contributor/index.md#suggested-practices-for-mentors-and-sub-organizations) +to publish selection checklists, clarify AI policies, and define engagement and +evaluation criteria before selection begins. Options include a newcomer-focused +project-use report before any pull request, daily updates on agreed working +days, and an internal rubric giving community engagement 50% of the assessment. +Each project can adopt, adjust, or omit these practices and should tell +candidates which ones apply. + ## Further Guidance - [GSoC Contributor Guide](../../gsoc/guides/contributor/index.md): preparing an From bc5880f06af301cfb80892b1965435bdff89f081 Mon Sep 17 00:00:00 2001 From: Ivan Ogasawara Date: Sat, 31 Oct 2026 10:13:29 -0400 Subject: [PATCH 3/5] docs: use direct guidance after a shared scope note --- .../gsoc/guides/contributor/index.md | 219 ++++++++---------- .../opportunities/guides/coding-tips/index.md | 52 ++--- .../guides/contribution/index.md | 108 ++++----- 3 files changed, 168 insertions(+), 211 deletions(-) diff --git a/pages/opportunities/gsoc/guides/contributor/index.md b/pages/opportunities/gsoc/guides/contributor/index.md index 888fe556f..1ff8cc659 100644 --- a/pages/opportunities/gsoc/guides/contributor/index.md +++ b/pages/opportunities/gsoc/guides/contributor/index.md @@ -1,69 +1,60 @@ # Google Summer of Code (GSoC) Contributor Guide -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. It also -includes -[suggested practices for mentors and sub-organizations](#suggested-practices-for-mentors-and-sub-organizations) -on publishing criteria, assessing engagement, and supporting contributors. - -Affiliated projects and sub-organizations may adopt, partially use, or adapt -OSL's [Contribution Guidelines](../../../guides/contribution/index.md) and -[Coding Tips](../../../guides/coding-tips/index.md). These are OSL's suggestions -for practices; check your project's own guidance to understand which practices -it follows. Official GSoC rules and applicable codes of conduct still apply. +These are Open Science Labs' (OSL) general recommendations for projects and +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. Official GSoC rules +and applicable codes of conduct still apply. + +This guide covers applications, initial contributions, collaboration, and +[suggested practices for mentors and sub-organizations](#suggested-practices-for-mentors-and-sub-organizations). +See also the [Contribution Guidelines](../../../guides/contribution/index.md) +and [Coding Tips](../../../guides/coding-tips/index.md). ## Candidates' Guide -This section outlines the steps candidates should follow to apply effectively. +Use the following steps to prepare your application. ### How to Apply #### 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. +Review the available sub-organizations and their projects. Choose a project that +aligns with your interests, skills, and learning goals. #### Initiating Contact with Projects and Mentors -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. +Introduce yourself to mentors in the designated communication channel. Explain +your interest and ask initial questions about the project or mentoring process. +Mentors: publish the contact channel and expected response times alongside the +project idea. #### Making an Initial Contribution -An initial contribution can demonstrate understanding of the project before any -code or pull request. A project may ask candidates to try a small, documented -workflow and write a short blog-style introduction or newcomer experience report -covering: +Before opening a pull request, try a small, documented workflow and write a +short blog post or newcomer experience report covering: - The project's mission, main objectives, and intended users. - How to install or access it and complete one useful example, with reproducible instructions for other newcomers. - What works well, what was confusing, and any setup or documentation obstacles. -- Constructive suggestions for improvement and what the candidate learned. +- Constructive suggestions for improvement and what you learned. -The project can use this as an initial selection criterion, provided it -announces the task, expected effort, deadline, and assessment criteria in -advance. A Markdown document or draft shared with mentors can be enough; a -personal blog, public publication, and a pull request need not be prerequisites. -If setup fails, documenting the steps tried and the blocker can still provide -useful evidence. +Mentors: use this report as an initial selection criterion and announce the +task, expected effort, deadline, submission channel, and assessment criteria in +advance. Accept a Markdown document or draft shared with the team without +requiring a personal blog or a pull request. If setup fails, document the steps +tried and the blocker so mentors can assess your approach and help resolve the +problem. -Candidates can then agree on a small follow-up contribution, such as improving -onboarding documentation, adding a test, or fixing a bug. Follow the project's -published sequence rather than assuming that opening many pull requests improves -selection chances. +Then agree on a small follow-up contribution with your 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. #### Crafting a Proposal with Mentor Support -Under mentor guidance, candidates should develop a detailed proposal that -outlines: +Develop a detailed proposal with mentor feedback that outlines: - **Milestones and Timeline:** Specific tasks and expected outcomes within the program period. @@ -71,48 +62,38 @@ outlines: - **Language and Style:** Clear, informative, and objective language; concise and focused content without unnecessary filler or marketing-style phrasing. -Read the project's AI-use policy before preparing the proposal or introductory -report. It should explain whether AI assistance is allowed, for which -activities, and what disclosure is expected. The submission should reflect the -candidate's own understanding; candidates should be able to explain and verify -everything they submit. Ask mentors if the policy is unclear. Writing style -alone is not evidence of AI use. - -Also check for project-specific proposal instructions. For example, a project -may ask for a short "Newcomer insight" section describing an onboarding obstacle -and one suggested improvement. Include the requested material so reviewers can -assess both your understanding and your attention to the project instructions. - -It is essential to review the -[contributor rules](https://summerofcode.withgoogle.com/rules) for the program -and follow the proposal template provided +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. Mentors: assess understanding through the +work and discussion; writing style alone is not evidence of AI use. + +Include a short "Newcomer insight" section describing an onboarding obstacle and +one suggested improvement. Use it to demonstrate what you learned from trying +the project and your attention to the proposal instructions. + +Review the [contributor rules](https://summerofcode.withgoogle.com/rules) for +the program and follow the proposal template provided [here](/opportunities/gsoc/templates/contributor-proposal). ## Review Process -Projects may publish a selection checklist with minimum criteria and a separate -scoring rubric. Read both before applying. Minimum criteria may cover the -introductory report, required proposal sections, AI-policy compliance, agreed -availability, and evidence of engagement. Projects should distinguish missing -requirements that make an application ineligible for their selection process -from preferences used to compare otherwise suitable candidates. - -Engagement can include asking thoughtful questions, responding to feedback, -sharing progress, helping others when appropriate, and following through on -agreed tasks. Quality and reliability matter more than message counts, constant -online presence, or the number of pull requests. A project may choose a rubric -with **50% community engagement and 50% technical understanding and project -planning**. This is a suggested project rubric; projects can adapt its weights -and criteria to their context. - -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. +Mentors: publish a selection checklist with minimum criteria and a separate +scoring rubric. Cover the introductory report, required proposal sections, +AI-policy compliance, agreed availability, and evidence of engagement. +Distinguish requirements that exclude an application from preferences used to +compare suitable candidates. Candidates: read both before applying. + +Assess engagement through thoughtful questions, responses to feedback, progress +updates, support for peers, and follow-through on agreed tasks. Prioritize +quality and reliability over message counts or constant online presence. Give +**50% of the assessment to community engagement and 50% to technical +understanding and project planning**. + +Provide clear feedback on proposals and discuss alternatives when another +project is a better fit. Candidates: notify mentors in the designated channel +when your proposal is ready for review. Keep general technical discussions +public and allow time for replies as mentors manage messages, issues, pull +requests, and reviews. ## Approved Contributors @@ -133,27 +114,24 @@ successful collaboration during the GSoC program with Open Science Labs. - **Use Designated Channels:** Communicate via the project’s preferred platforms to ensure transparency and prompt feedback. -A project may ask for a brief daily status report to the mentor on agreed -working days. Agree on the channel and delivery window, accounting for time -zones and planned absences. A shared thread or project log can avoid repeated -direct messages and let other mentors help. A useful format is: +Send a brief daily status report to your mentor on agreed working days. Agree on +the channel and delivery window, accounting for time zones and planned absences. +Use a shared thread or project log so other mentors can also help. 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. -Reporting a blocker is useful even when no code was completed. Mentors should -review updates and respond to requests for help. Daily reporting supports -coordination; it is not a requirement to be online continuously or work every -calendar day. During selection, any reporting exercise should be announced in -advance and limited to a short, defined activity. +Report blockers even when no code was completed. Mentors: review updates and +respond to requests for help. Respect agreed working days and absences. During +selection, announce any reporting exercise in advance and limit it to a short, +defined activity. ### Programming Best Practices For practical suggestions on code readability, focused pull requests, testing, and AI-assisted work, see OSL's -[Coding Tips](../../../guides/coding-tips/index.md). Use them alongside the -practices adopted by your project and agreed with your mentor. +[Coding Tips](../../../guides/coding-tips/index.md). - **Adherence to Standards:** Follow the coding standards and best practices outlined by your mentor and project guidelines. @@ -163,11 +141,9 @@ practices adopted by your project and agreed with your mentor. ## Suggested Practices for Mentors and Sub-Organizations -OSL suggests the following practices. Each project can follow them in full, -select the parts that help, or adapt them to its context, and should explain its -choices to candidates **before the selection period begins**. Confirm the -working agreement with selected contributors during community bonding, including -any agreed adjustments. +Publish selection criteria and contributor expectations **before the selection +period begins**. Confirm the working agreement with selected contributors during +community bonding, including any agreed adjustments. ### Publish a Selection Checklist @@ -191,12 +167,12 @@ does not guarantee a slot. Additional project criteria are separate from ### Check That Instructions Were Read -A small, explicit, project-relevant instruction can help assess whether a -candidate read the guidance. For example, request a "Newcomer insight" section -with one observation from trying the project. Include it in the proposal -instructions and checklist, and explain how omissions are handled. Prefer a -useful task over an unrelated secret phrase or personal trivia; it gives mentors -evidence they can discuss with the candidate. +Include a small, explicit, project-relevant instruction to check that candidates +read the guidance. Request a "Newcomer insight" section with one observation +from trying the project. Include it in the proposal instructions and checklist, +and explain how omissions are handled. Prefer a useful task over an unrelated +secret phrase or personal trivia; it gives mentors evidence they can discuss +with the candidate. ### Make the AI Policy Specific @@ -205,16 +181,14 @@ reports, code, tests, and documentation. State whether editing, translation, brainstorming, or code generation is allowed; what tools or data restrictions apply; and how assistance should be disclosed. Describe how suspected violations will be reviewed and let candidates explain their work. Link the policy from the -project idea, proposal instructions, and contribution guide. Do not assume every -OSL-affiliated project uses the same policy. +project idea, proposal instructions, and contribution guide. ### Give Community Engagement Explicit Weight -Projects may choose to assign **50% of their internal assessment to community -engagement**. The remaining 50% can assess technical understanding and planning -during selection, or agreed deliverables and code quality during the program. -Publish the rubric, evidence, and any minimum thresholds for both areas. For -example: +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 any minimum thresholds for both areas. For example: | Area | Weight | Evidence to consider | | ------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | @@ -226,8 +200,8 @@ example: 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. This example is not Google's evaluation formula -and does not replace official GSoC evaluation requirements. +to meet agreed technical goals. Use this rubric for internal assessment +alongside the official GSoC evaluation requirements. ### Set Expectations and Address Problems Early @@ -242,13 +216,13 @@ identify blockers and any gaps in mentoring support, and agree on concrete next steps and a review date. Distinguish persistent failure to follow through from an agreed absence or a technical obstacle raised promptly. -It is appropriate to decline candidates who do not meet published selection -criteria. During the program, mentors should 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 OSL's organization administrators, document the basis for the decision, and -follow the current GSoC evaluation process. Concerns should be communicated -early so the evaluation is not the first notice of a problem. +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 OSL's organization +administrators, 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), @@ -257,10 +231,9 @@ and [Evaluations](https://google.github.io/gsocguides/mentor/evaluations). ## 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). +Consult the [GSoC Student Guide](https://google.github.io/gsocguides/student/) +for comprehensive details on the application process and proposal preparation. +Read Google's +[advice for contributors](https://developers.google.com/open-source/gsoc/help/student-advice) +and use the +[proposal template](/opportunities/gsoc/templates/contributor-proposal). diff --git a/pages/opportunities/guides/coding-tips/index.md b/pages/opportunities/guides/coding-tips/index.md index 78ba16b9f..fea58425f 100644 --- a/pages/opportunities/guides/coding-tips/index.md +++ b/pages/opportunities/guides/coding-tips/index.md @@ -10,11 +10,11 @@ template: single-sidebar.html # Coding Tips -Open Science Labs (OSL) shares these recommendations with affiliated projects, -including sub-organizations participating in GSoC with us. Projects may follow -them completely, select the parts that help, or adapt them to their language, -tooling, and community. Contributors should follow the practices their project -has adopted and ask maintainers when something is unclear. +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 @@ -30,8 +30,7 @@ technical side of a contribution. - 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. - Projects can document or automate these commands to make onboarding easier and - choose the tools that fit their workflow. + Document and automate recurring commands to make onboarding easier. ## Keep Changes Small and Focused @@ -39,9 +38,9 @@ technical side of a contribution. 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. -- If a project chooses a pull request size guideline, treat it as a review aid - and explain exceptions. Generated files and related tests may affect the size; - line count alone does not determine whether a change is manageable. +- 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. @@ -50,8 +49,8 @@ technical side of a contribution. - 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. Around four levels can be a useful prompt to - reconsider the structure, rather than a universal limit. + 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 @@ -71,10 +70,9 @@ pre-commit install pre-commit run --all-files ``` -Use the project's installation instructions first. These commands apply to -projects with a `pre-commit` configuration; other projects may provide different -checks. Inspect any automatic changes and include only those relevant to your -contribution. +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 @@ -98,17 +96,17 @@ in the pull request so reviewers know what remains unverified. ## Use AI Tools Responsibly -Projects can decide whether AI-assisted contributions are allowed and under -which conditions. Maintainers can publish that policy in their contribution -guide, including any disclosure expectations. - -Where use is allowed, 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. +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 diff --git a/pages/opportunities/guides/contribution/index.md b/pages/opportunities/guides/contribution/index.md index dcb2a8b71..a2aca508e 100644 --- a/pages/opportunities/guides/contribution/index.md +++ b/pages/opportunities/guides/contribution/index.md @@ -10,23 +10,16 @@ template: single-sidebar.html # Contribution Guidelines -Open Science Labs (OSL) offers this guide to affiliated projects and -sub-organizations participating in Google Summer of Code (GSoC) with us. It is a -starting point for building a welcoming, sustainable contribution process. -Projects can adopt it in full, use selected recommendations, or adapt it to -their community, tools, and mentoring capacity. It can also support projects in -other OSL contribution and internship initiatives. +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. -These are OSL's suggestions for contribution practices. Each project can choose -which suggestions to follow or adapt. Contributors should read their project's -own contribution guide and ask maintainers which practices apply. Applicable -codes of conduct and official program rules still apply independently of this -guide. +## Prepare Contribution Resources -## Adapting This Guide for Your Project - -Maintainers and mentors may find it useful to publish a `CONTRIBUTING.md` file -and issue or pull request templates covering: +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. @@ -37,67 +30,62 @@ and issue or pull request templates covering: 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. Our separate [Coding Tips](../coding-tips/index.md) page offers technical -practices projects can select or adapt alongside this guide. +adapt. Include the technical practices described in +[Coding Tips](../coding-tips/index.md) in your onboarding resources. ## Community Engagement -- **Communication Platforms:** Projects can choose the platforms that work for - their community, such as GitHub, GitLab, Discord, or Slack. Publish where - contributors can seek help, discuss ideas, and request reviews. Public - discussions help others learn; private channels are appropriate for sensitive - matters or when the project's process calls for them. +- **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:** Contributors are encouraged to assist others - when possible, as everyone is here to learn and support one another. +- **Collaboration and Support:** Help others when possible. Share what you learn + and support fellow contributors as they develop their 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. +- **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. -- **Channel Usage:** If a project coordinates in chat, contributors can share - links to relevant issues or pull requests there. Projects may prefer a - discussion before substantial work begins; make that preference clear without - requiring a separate chat discussion for every small contribution. +- **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. - **Mentoring and Progress:** For GSoC, agree on realistic check-in times, - progress updates, and a way to raise blockers. Short regular meetings and - written next steps can help. Consider time zones, accessibility needs, and - mentor availability when choosing a routine. + 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:** Before starting, check whether a task is still relevant and whether someone is already working on it. Comment on the issue or use the - project's preferred channel to coordinate. Maintainers can offer small starter - tasks and examples of helpful contributions, including documentation and - tests. + 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. -- **Preparing for Review:** A useful pull request explains the problem, the - proposed change, and how it was checked. Link related issues, follow the - project's templates, and describe any remaining questions. Draft mode is - helpful for work in progress; mark it ready when it meets the project's review - expectations. +- **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. -- **Reviewing Together:** Treat review as a chance to learn. Contributors can - respond to feedback and explain tradeoffs; reviewers can distinguish required - changes from suggestions and explain their reasoning. Allow time for replies - before following up through the agreed channel. +- **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. -- **Managing Inactive Work:** Projects may choose to label, return to draft, or - close inactive issues and pull requests. Publish any timeframes, check in with - the contributor first, and explain how work can resume. Consider both - contributor circumstances and delays in mentor or maintainer feedback. +- **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:** When updating a branch, contributors should follow the - project's preferred approach, whether that involves using a **rebase** or a - **merge commit**. +- **Branch Management:** Document whether branch updates use a **rebase** or a + **merge commit**, and use that approach consistently. ## Coding Tips @@ -108,14 +96,12 @@ responsible use of AI tools. ## GSoC Selection and Mentoring -Projects participating in GSoC with OSL can use the +Use the [suggested practices for mentors and sub-organizations](../../gsoc/guides/contributor/index.md#suggested-practices-for-mentors-and-sub-organizations) to publish selection checklists, clarify AI policies, and define engagement and -evaluation criteria before selection begins. Options include a newcomer-focused -project-use report before any pull request, daily updates on agreed working -days, and an internal rubric giving community engagement 50% of the assessment. -Each project can adopt, adjust, or omit these practices and should tell -candidates which ones apply. +evaluation criteria before selection begins. Start with a newcomer-focused +project-use report before any pull request, send daily updates on agreed working +days, and give community engagement 50% of the internal assessment. ## Further Guidance From bfa8a32353e9dece7440347dd572590e3a3c18a1 Mon Sep 17 00:00:00 2001 From: Ivan Ogasawara Date: Sun, 1 Nov 2026 04:25:07 -0400 Subject: [PATCH 4/5] docs: organize GSoC guidance by role and emphasize user experience --- mkdocs.yml | 2 +- .../gsoc/guides/contributor/index.md | 404 ++++++++++-------- pages/opportunities/gsoc/index.md | 20 +- .../guides/contribution/index.md | 20 +- 4 files changed, 256 insertions(+), 190 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index bd8ca56c4..a68cbb4db 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,7 +69,7 @@ nav: - Project Ideas: "opportunities/gsoc/project-ideas/index.md" - "Contribution Guidelines": "opportunities/guides/contribution/index.md" - "Coding Tips": "opportunities/guides/coding-tips/index.md" - - "Candidates' Guide": "opportunities/gsoc/guides/contributor/index.md" + - "GSoC Guide": "opportunities/gsoc/guides/contributor/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/contributor/index.md b/pages/opportunities/gsoc/guides/contributor/index.md index 1ff8cc659..f364c7cfa 100644 --- a/pages/opportunities/gsoc/guides/contributor/index.md +++ b/pages/opportunities/gsoc/guides/contributor/index.md @@ -1,239 +1,295 @@ -# Google Summer of Code (GSoC) Contributor Guide +# Google Summer of Code (GSoC) Guide These are Open Science Labs' (OSL) general recommendations for projects and 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. Official GSoC rules -and applicable codes of conduct still apply. +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. -This guide covers applications, initial contributions, collaboration, and -[suggested practices for mentors and sub-organizations](#suggested-practices-for-mentors-and-sub-organizations). -See also the [Contribution Guidelines](../../../guides/contribution/index.md) -and [Coding Tips](../../../guides/coding-tips/index.md). - -## Candidates' Guide - -Use the following steps to prepare your application. - -### How to Apply - -#### Selecting a Sub-Organization/Project +Find the recommendations for your role: -Review the available sub-organizations and their projects. Choose a project that -aligns with your interests, skills, and learning goals. +- [Organization Admins](#organization-admins): coordinate participation, mentor + capacity, selection, and evaluation across projects. +- [Mentors](#mentors): prepare project guidance, assess candidates, and support + contributors throughout the program. +- [Contributor Candidates](#contributor-candidates): get to know the community, + use the software, prepare an application, and collaborate after selection. -#### Initiating Contact with Projects and Mentors - -Introduce yourself to mentors in the designated communication channel. Explain -your interest and ask initial questions about the project or mentoring process. -Mentors: publish the contact channel and expected response times alongside the -project idea. - -#### Making an Initial Contribution - -Before opening a pull request, try a small, documented workflow and write a -short blog post or newcomer experience report covering: - -- The project's mission, main objectives, and intended users. -- How to install or access it and complete one useful example, with reproducible - instructions for other newcomers. -- What works well, what was confusing, and any setup or documentation obstacles. -- Constructive suggestions for improvement and what you learned. - -Mentors: use this report as an initial selection criterion and announce the -task, expected effort, deadline, submission channel, and assessment criteria in -advance. Accept a Markdown document or draft shared with the team without -requiring a personal blog or a pull request. If setup fails, document the steps -tried and the blocker so mentors can assess your approach and help resolve the -problem. - -Then agree on a small follow-up contribution with your 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. +See also the [Contribution Guidelines](../../../guides/contribution/index.md) +and [Coding Tips](../../../guides/coding-tips/index.md). -#### Crafting a Proposal with Mentor Support +## Organization Admins -Develop a detailed proposal with mentor feedback that outlines: +### Coordinate Participation and Mentor Capacity -- **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. +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. -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. Mentors: assess understanding through the -work and discussion; writing style alone is not evidence of AI use. +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. -Include a short "Newcomer insight" section describing an onboarding obstacle and -one suggested improvement. Use it to demonstrate what you learned from trying -the project and your attention to the proposal instructions. +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. -Review the [contributor rules](https://summerofcode.withgoogle.com/rules) for -the program and follow the proposal template provided -[here](/opportunities/gsoc/templates/contributor-proposal). +### Publish the Selection Framework -## Review Process +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. -Mentors: publish a selection checklist with minimum criteria and a separate -scoring rubric. Cover the introductory report, required proposal sections, -AI-policy compliance, agreed availability, and evidence of engagement. -Distinguish requirements that exclude an application from preferences used to -compare suitable candidates. Candidates: read both before applying. +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. -Assess engagement through thoughtful questions, responses to feedback, progress -updates, support for peers, and follow-through on agreed tasks. Prioritize -quality and reliability over message counts or constant online presence. Give -**50% of the assessment to community engagement and 50% to technical -understanding and project planning**. +### Give Community Engagement Explicit Weight -Provide clear feedback on proposals and discuss alternatives when another -project is a better fit. Candidates: notify mentors in the designated channel -when your proposal is ready for review. Keep general technical discussions -public and allow time for replies as mentors manage messages, issues, pull -requests, and reviews. +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: -## Approved Contributors +| 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. | -For accepted candidates, the following guidelines serve as a roadmap for -successful collaboration during the GSoC program with Open Science Labs. +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. -### Effective Workflow and Proactivity +### Support Consistent Decisions and Resolve Problems -- **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. +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. -### Communication Best Practices +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. -- **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. + -Send a brief daily status report to your mentor on agreed working days. Agree on -the channel and delivery window, accounting for time zones and planned absences. -Use a shared thread or project log so other mentors can also help. Include: +## Mentors -- **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. +### Prepare the Project and Welcome Candidates -Report blockers even when no code was completed. Mentors: review updates and -respond to requests for help. Respect agreed working days and absences. During -selection, announce any reporting exercise in advance and limit it to a short, -defined activity. +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. -### Programming Best Practices +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. -For practical suggestions on code readability, focused pull requests, testing, -and AI-assisted work, see OSL's -[Coding Tips](../../../guides/coding-tips/index.md). +### Use a Project Experience Report as the First Contribution -- **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. +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. -## Suggested Practices for Mentors and Sub-Organizations +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. -Publish selection criteria and contributor expectations **before the selection -period begins**. Confirm the working agreement with selected contributors during -community bonding, including any agreed adjustments. +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 Selection Checklist +### Publish a Project Selection Checklist -Separate minimum requirements from scored preferences. For each minimum, state -what evidence is expected, the deadline, whether clarification or correction is -possible, and when failure to meet it excludes an application. For example: +Align project criteria with the organization's selection framework. For example: - [ ] The applicant meets the current official GSoC eligibility requirements. -- [ ] The introductory project-use report meets the published criteria. -- [ ] The proposal includes the requested sections and demonstrates - understanding of the project's goals. +- [ ] 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 - communication windows. + windows. - [ ] Availability and proposed scope are realistic for the project. -Use the same published criteria consistently, document selection reasons, and -allow agreed accessibility or scheduling accommodations. Meeting the checklist -does not guarantee a slot. Additional project criteria are separate from -[Google's official rules](https://summerofcode.withgoogle.com/rules). - -### Check That Instructions Were Read - Include a small, explicit, project-relevant instruction to check that candidates -read the guidance. Request a "Newcomer insight" section with one observation -from trying the project. Include it in the proposal instructions and checklist, -and explain how omissions are handled. Prefer a useful task over an unrelated -secret phrase or personal trivia; it gives mentors evidence they can discuss -with the candidate. +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, introductory +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 should be disclosed. Describe how suspected violations -will be reviewed and let candidates explain their work. Link the policy from the -project idea, proposal instructions, and contribution guide. - -### Give Community Engagement Explicit Weight +apply; and how assistance must be disclosed. Link the policy from the project +idea, proposal instructions, and contribution guide. -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 any 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% | Newcomer insights, 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 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. -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. +### Review Proposals and Agree on Expectations -### Set Expectations and Address Problems Early +Assess proposals using the published checklist and rubric. 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. Explain what happens when expectations are repeatedly -unmet. Also state mentor responsibilities, including availability, review -turnaround, and a backup contact. Keep a shared record of agreed changes. +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 any gaps in mentoring support, and agree on concrete next -steps and a review date. Distinguish persistent failure to follow through from -an agreed absence or a technical obstacle raised promptly. +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 OSL's organization -administrators, document the basis for the decision, and follow the current GSoC -evaluation process. Communicate concerns early and provide feedback before the -evaluation. +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). -## Proposal Resources + + +## Contributor Candidates + +### 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 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/) -for comprehensive details on the application process and proposal preparation. -Read Google's +and Google's [advice for contributors](https://developers.google.com/open-source/gsoc/help/student-advice) -and use the -[proposal template](/opportunities/gsoc/templates/contributor-proposal). +for further application guidance. diff --git a/pages/opportunities/gsoc/index.md b/pages/opportunities/gsoc/index.md index ef9979c2f..02dfb1f26 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 guide for +[organization admins](guides/contributor/index.md#organization-admins) and +[mentors](guides/contributor/index.md#mentors) 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/contributor/index.md#contributor-candidates) +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/contribution/index.md b/pages/opportunities/guides/contribution/index.md index a2aca508e..3817802e1 100644 --- a/pages/opportunities/guides/contribution/index.md +++ b/pages/opportunities/guides/contribution/index.md @@ -96,16 +96,20 @@ responsible use of AI tools. ## GSoC Selection and Mentoring -Use the -[suggested practices for mentors and sub-organizations](../../gsoc/guides/contributor/index.md#suggested-practices-for-mentors-and-sub-organizations) -to publish selection checklists, clarify AI policies, and define engagement and -evaluation criteria before selection begins. Start with a newcomer-focused -project-use report before any pull request, send daily updates on agreed working -days, and give community engagement 50% of the internal assessment. +Read the recommendations for your role in the GSoC guide: + +- [Organization Admins](../../gsoc/guides/contributor/index.md#organization-admins): + coordinate participation, mentor capacity, selection criteria, and + evaluations. +- [Mentors](../../gsoc/guides/contributor/index.md#mentors): prepare project + guidance, review candidates, and support contributor progress. +- [Contributor Candidates](../../gsoc/guides/contributor/index.md#contributor-candidates): + contact the community, explore the software, write about your experience, and + prepare an application. ## Further Guidance -- [GSoC Contributor Guide](../../gsoc/guides/contributor/index.md): preparing an - application and working with mentors. +- [GSoC Guide](../../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. From 25564a473e5ee3b93cedb62f0160a34d082b6eeb Mon Sep 17 00:00:00 2001 From: Ivan Ogasawara Date: Sun, 1 Nov 2026 04:36:40 -0400 Subject: [PATCH 5/5] docs: split GSoC recommendations into role guides --- mkdocs.yml | 5 +- .../gsoc/guides/candidates/index.md | 115 +++++++ .../gsoc/guides/contributor/index.md | 289 ++---------------- .../gsoc/guides/mentors/index.md | 116 +++++++ .../gsoc/guides/organization-admins/index.md | 75 +++++ pages/opportunities/gsoc/index.md | 14 +- .../guides/contribution/index.md | 16 +- 7 files changed, 347 insertions(+), 283 deletions(-) create mode 100644 pages/opportunities/gsoc/guides/candidates/index.md create mode 100644 pages/opportunities/gsoc/guides/mentors/index.md create mode 100644 pages/opportunities/gsoc/guides/organization-admins/index.md diff --git a/mkdocs.yml b/mkdocs.yml index a68cbb4db..80dae895b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,7 +69,10 @@ nav: - Project Ideas: "opportunities/gsoc/project-ideas/index.md" - "Contribution Guidelines": "opportunities/guides/contribution/index.md" - "Coding Tips": "opportunities/guides/coding-tips/index.md" - - "GSoC Guide": "opportunities/gsoc/guides/contributor/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 f364c7cfa..67ca1a477 100644 --- a/pages/opportunities/gsoc/guides/contributor/index.md +++ b/pages/opportunities/gsoc/guides/contributor/index.md @@ -1,4 +1,4 @@ -# Google Summer of Code (GSoC) Guide +# Google Summer of Code (GSoC) Guides These are Open Science Labs' (OSL) general recommendations for projects and sub-organizations participating in Google Summer of Code (GSoC) under the OSL @@ -7,289 +7,44 @@ 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. -Find the recommendations for your role: - -- [Organization Admins](#organization-admins): coordinate participation, mentor - capacity, selection, and evaluation across projects. -- [Mentors](#mentors): prepare project guidance, assess candidates, and support - contributors throughout the program. -- [Contributor Candidates](#contributor-candidates): get to know the community, - use the software, prepare an application, and collaborate after selection. - -See also the [Contribution Guidelines](../../../guides/contribution/index.md) -and [Coding Tips](../../../guides/coding-tips/index.md). +Choose the guide for your role. Each page contains the full recommendations for +that role, with links to shared contribution and coding guidance. ## Organization Admins -### 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. +[Read the Organization Admins Guide](../organization-admins/index.md) to +coordinate participation, mentor capacity, selection criteria, engagement +assessment, and evaluation decisions across projects. ## Mentors -### 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. 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 rubric. 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). +[Read the Mentors Guide](../mentors/index.md) to prepare project guidance, +welcome and assess candidates, publish AI policies, set expectations, and +support contributor progress. ## Contributor Candidates -### 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. +[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. -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 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%. +For application review, see the +[candidate review process](../candidates/index.md#review-process). -### 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. +After selection, follow the guidance on +[working with your mentor](../candidates/index.md#after-selection-work-with-your-mentor). -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. +## Shared Guidance -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. +- [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 02dfb1f26..f3c4d044c 100644 --- a/pages/opportunities/gsoc/index.md +++ b/pages/opportunities/gsoc/index.md @@ -44,10 +44,10 @@ project by email to by January 31, 2026. Check out our project idea template for more insights: . -Read the GSoC guide for -[organization admins](guides/contributor/index.md#organization-admins) and -[mentors](guides/contributor/index.md#mentors) to prepare participation, -selection, and mentoring. +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 @@ -58,9 +58,9 @@ its ideas, onboarding, and technical discussions. 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 -[GSoC Guide for Contributor Candidates](guides/contributor/index.md#contributor-candidates) -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 diff --git a/pages/opportunities/guides/contribution/index.md b/pages/opportunities/guides/contribution/index.md index 3817802e1..9ca61bc2a 100644 --- a/pages/opportunities/guides/contribution/index.md +++ b/pages/opportunities/guides/contribution/index.md @@ -98,18 +98,18 @@ responsible use of AI tools. Read the recommendations for your role in the GSoC guide: -- [Organization Admins](../../gsoc/guides/contributor/index.md#organization-admins): +- [Organization Admins](../../gsoc/guides/organization-admins/index.md): coordinate participation, mentor capacity, selection criteria, and evaluations. -- [Mentors](../../gsoc/guides/contributor/index.md#mentors): prepare project - guidance, review candidates, and support contributor progress. -- [Contributor Candidates](../../gsoc/guides/contributor/index.md#contributor-candidates): - contact the community, explore the software, write about your experience, and - prepare an application. +- [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 Guide](../../gsoc/guides/contributor/index.md): recommendations for - organization admins, mentors, and contributor candidates. +- [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.