From 1089a34c86e64d573790e5289d84e572a45dcaef Mon Sep 17 00:00:00 2001 From: Alya Abbott Date: Sun, 18 Sep 2022 23:38:08 -0700 Subject: [PATCH] docs: Reorganize contribution documentation. * Make an "Outreach programs" documentation directory. * Revamp doc on having an amazing outreach program experience. * Extract an outreach programs overview page from GSoC guide. * Add a guide on making PRs easy to review, extracted from "How to have an amazing summer with Zulip". * Create a guide for mentors, extracted from "How to have an amazing summer with Zulip". * Add a guide on how to ask great questions extracted from GSoC guide. * Extract general page on applying to outreach programs from GSoC guide. * Simplify GSoC guide page to just describe project ideas. * Many local edits to the reorganized content. --- docs/contributing/asking-great-questions.md | 54 ++++ docs/contributing/index.md | 4 +- docs/contributing/reviewable-prs.md | 73 +++++ docs/contributing/summer-with-zulip.md | 295 ------------------ docs/index.md | 10 + docs/outreach/apply.md | 188 +++++++++++ docs/outreach/experience.md | 327 ++++++++++++++++++++ docs/{contributing => outreach}/gsoc.md | 276 ++--------------- docs/outreach/index.md | 13 + docs/outreach/mentoring.md | 100 ++++++ docs/outreach/overview.md | 74 +++++ 11 files changed, 870 insertions(+), 544 deletions(-) create mode 100644 docs/contributing/asking-great-questions.md create mode 100644 docs/contributing/reviewable-prs.md delete mode 100644 docs/contributing/summer-with-zulip.md create mode 100644 docs/outreach/apply.md create mode 100644 docs/outreach/experience.md rename docs/{contributing => outreach}/gsoc.md (63%) create mode 100644 docs/outreach/index.md create mode 100644 docs/outreach/mentoring.md create mode 100644 docs/outreach/overview.md diff --git a/docs/contributing/asking-great-questions.md b/docs/contributing/asking-great-questions.md new file mode 100644 index 0000000000..9d2890d83a --- /dev/null +++ b/docs/contributing/asking-great-questions.md @@ -0,0 +1,54 @@ +# Asking great questions + +A well-formed question helps you learn, respects the person answering, and makes +efficient use of time for everyone involved. Asking the right question, to the +right person, in the right way, at the right time, is a skill which requires a +lifetime of fine-tuning. This page offers some guidelines and resources that the +[Zulip community](https://zulip.com/development-community/) has found helpful in this pursuit. + +## Where to ask your question + +It is almost always best to ask questions and have a conversation in a public +stream, rather than in private messages. You’ll get better and faster answers +since many people can help, and it makes it possible for others to benefit from +the discussion. + +The [Zulip community +guide](https://zulip.com/development-community/#where-do-i-send-my-message) +offers guidelines on how the major public streams in the community are used. +Don’t stress too much about picking the right place if you’re not sure, as +moderators can [move your question thread to a different +stream](https://zulip.com/help/move-content-to-another-stream) if needed. + +## How to ask a great question + +Spending some extra time and effort to carefully formulate your question is well +worthwhile, as it makes it much more likely that you'll get the information you +need to move forward. There are a few wonderfully thoughtful blog posts that +explain what it means to ask a good question: + +- [Try, Then Ask](https://www.mattringel.com/2013/09/30/you-must-try-and-then-you-must-ask/) +- [We Aren’t Just Making Code, We’re Making History](https://www.harihareswara.net/sumana/2016/10/12/0) +- [How to Ask Good Questions](https://jvns.ca/blog/good-questions/) + +In brief, to formulate a great question, you should: + +- Try to solve your own problem first, including reading through relevant + documentation and code. +- Identify the precise point on which you feel stuck. +- Formulate a clear question, which includes an appropriate amount of context + and a specific request for help. + +When your question is answered, follow through on the advice you receive, and (when +appropriate) summarize the resolution of your problem so that others can learn +from your experience. + +You can find additional helpful tips in our guide to [what makes a great Zulip +contributor](contributing.md#what-makes-a-great-zulip-contributor). + +## Follow the community guidelines + +As always, be sure to follow the [Zulip community +norms](https://zulip.com/development-community/). In particular, check out [the +section on getting help](https://zulip.com/development-community/#getting-help) +before you post. diff --git a/docs/contributing/index.md b/docs/contributing/index.md index daaa94a29d..1604919e3b 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -7,12 +7,12 @@ maxdepth: 3 contributing ../code-of-conduct +asking-great-questions version-control code-style +reviewable-prs code-reviewing zulipbot-usage bug-reports -gsoc -summer-with-zulip licensing ``` diff --git a/docs/contributing/reviewable-prs.md b/docs/contributing/reviewable-prs.md new file mode 100644 index 0000000000..0e2215db60 --- /dev/null +++ b/docs/contributing/reviewable-prs.md @@ -0,0 +1,73 @@ +# Reviewable pull requests + +This page offers some tips for making your pull requests easy to review. +Following this advice will help the whole Zulip project move more quickly by +saving maintainers time when they review your code. It will also make a big +difference for getting your work integrated without delay. + +## Posting a pull request + +- Before requesting a review for your pull request, follow our guide to + carefully [review and test your own + code](./code-reviewing.md#reviewing-your-own-code). Doing so can save many + review round-trips. + +- Make sure the pull request template is filled out correctly, and that all the + relevant points on the self-review checklist (if the repository has one) have + been addressed. + +- Be sure to explicitly call out any open questions, concerns, or decisions you + are uncertain about. + +## Addressing feedback + +- When you update your PR after addressing a round of review feedback, be clear + about which issues you've resolved (and how!). + +- Even more importantly, save time for your reviewers by indicating any feedback + you _haven't_ addressed yet. + +## Working on larger projects + +For a larger project, aim to create a series of small (less than 100 lines of +code) commits that are each safely mergeable and move you towards your goal. A +mergeable commit: + +- Is well-tested and passes all the tests. That is, changes to tests should be in + the same commit as changes to the code that they are testing. + +- Does not make Zulip worse. For example, it is fine to add backend capabilities + without adding a frontend to access them. It's not fine to add a frontend + component with no backend to make it work. + +Ideally, when reviewing a branch you are working on, the maintainer +should be able to verify and merge the first few commits and leave +comments on the rest. It is by far the most efficient way to do +collaborative development, since one is constantly making progress, we +keep branches small, and developers don't end up repeatedly reviewing +the earlier parts of a PR. + +Here is some advice on how to proceed: + +- Use `git rebase -i` as much as you need to shape your commit + structure. See the [Git guide](../git/overview.md) for useful + resources on mastering Git. + +- If you need to refactor code, add tests, rename variables, or make + other changes that do not change the functionality of the product, make those + changes into a series of preparatory commits that can be merged independently + of building the feature itself. + +- To figure out what refactoring needs to happen, you might first make a hacky + attempt at hooking together the feature, with reading and print statements as + part of the effort, to identify any refactoring needed or tests you want to + write to help make sure your changes won't break anything important as you work. + Work out a fast and consistent test procedure for how to make sure the + feature is working as planned. + +- Build a mergeable version of the feature on top of those refactorings. + Whenever possible, find chunks of complexity that you can separate from the + rest of the project. + +See our [commit discipline guide](../contributing/version-control.md) for +more details on writing reviewable commits. diff --git a/docs/contributing/summer-with-zulip.md b/docs/contributing/summer-with-zulip.md deleted file mode 100644 index 3721583f4e..0000000000 --- a/docs/contributing/summer-with-zulip.md +++ /dev/null @@ -1,295 +0,0 @@ -# How to have an amazing summer with Zulip - -The purpose of this doc is to provide advice to GSoC/ZSoC mentors and contributors -on how to make the summer as successful as possible. It's mandatory reading, in -addition to [Google's -materials](https://developers.google.com/open-source/gsoc/resources/manual). - -- Don't focus too much on doing precisely what's in the project proposal or - following precisely that schedule. The goals are for contributors to learn and to - advance Zulip, not to do in July what we guessed would be the right plan in - March with limited information. - - - We probably will want to create a Dropbox Paper document for each contributor to - keep track of the current version of their project plan, but make sure to - keep GitHub up to date with what issues you're working on. - - - Claim issues using zulipbot only when you actually start work on them. And - if someone else fixes an issue you were planning to fix, don't worry about - it! It's great for Zulip that the project was finished, and there's plenty - of issues to work on :D. You can help review their work to build - your expertise in the subsystem you're working on. - - - Look for, claim, and fix bugs to help keep Zulip polished. Bugs and polish - are usually more important to users than new features. - - - Help test new features! It's fun, and one of the most valuable - ways one can contribute to any software project is finding bugs in - it before they reach a lot of users :). - - - Participate and be helpful in the community! Helping a new Zulip server - administrator debug their installation problem or playing with the mobile - app until you can get something to break are great ways to contribute. - -- Mentors and contributors should stay in close contact, both with each other and - the rest of the Zulip community. We recommend the following: - - - Daily checkins on #checkins in - [the Zulip development community](https://zulip.com/development-community/); ideally - at some time of day you can both be online, but when not - possible, async is better than nothing! - - - We prefer checkins in public streams, since it makes easier for - other contributors to keep track of what everyone else is - working on and share ideas (and helps organization leadership - keep track of progress). Though, of course, feel free to have - much more involved/detailed discussions privately as well. - - - If a mentor will be traveling or otherwise offline, mentors should make - sure another mentor is paying attention in the meantime. - - - Video calls are great! Mentors should do 1-2 video calls with their contributors - calls per week, depending on length, schedules, and what's happening. - - - Make sure to talk about not just the current project, but also meta-issues - like your development process, where things are getting stuck, skills you - need help learning, and time-saving tricks. - - - If you need feedback from the community / decisions made, ask in the - appropriate public stream in - [the Zulip development community](https://zulip.com/development-community/). Often - someone can provide important context that you need to succeed in your project. - - - Communicate clearly, especially in public places! You'll get much more - useful feedback to a well-written Zulip message or GitHub issue comment than - one that is unclear. - - - Be sure to mention any concerns you have with your own work! - - - Talk with your mentor about the status of your various projects and where - they're stuck. - - - And when you update your PR having addressed a set of review feedback, be - clear about which issues you've resolved (and how!) and - especially any that you haven't yet (this helps code reviewers - use their time well). - - - Post screenshots and/or brief videos of UI changes; a picture can be worth - 1000 words, especially for verifying whether a design change is - working as intended. - - - Use #design and similar forums to get feedback on issues where we need - community consensus on what something should look like or how it - should work. - - - Bring up problems early, whether technical or otherwise. If you - find you're stressed about something, mention it your mentor - immediately, so they can help you solve the problem. If you're - stressed about something involving your mentor, bring it up with - an organization admin. - - - If you work in one a smaller Zulip project - (e.g. `zulip-terminal`), follow the project on GitHub so you can - keep track of what's happening there. For folks working in - `zulip/zulip`, doing that will send you too many notifications. - So instead, we recommend that you join Zulip's GitHub teams that - relate to your projects and/or interests, so that you see new - issues and PRs coming in that are relevant to your work. When we - label an issue or PR with one of our area labels, `zulipbot` will - automatically mention the relevant teams for that area, - subscribing you to those issues/PR threads. You can browse the - area teams here: https://github.com/orgs/zulip/teams (You need to - be a member of the Zulip organization to see them; - ask Tim for an invite if needed). - -- Everyone's goal is to avoid contributors ending up blocked and feeling stuck. - There are lots of things that contributors can do (and mentors can help them to) - to avoid this: - - - Get really good at using `git rebase -i` to produce a really clean - commit history that's fast to review. We occasionally do workshops - on how to do relatively complex rebases. - - - Work on multiple parallelizable projects (or parts of projects) at a time. - This can help avoid being stuck while waiting for something to be reviewed. - - - It can help to plan a bit in advance; if your next project requires some - UX decisions to be made with the community, start the conversation a few - days before you need an answer. Or do some preparatory refactoring that - will make the feature easier to complete and can be merged without making - all the decisions. - - - Think about how to test your changes. - - - Among your various projects, prioritize as follows: - - - (1) Fixing regressions you introduced with recently merged work (and other - bugs you notice). - - - (2) Responding to code review feedback and fixing your in-flight branches - over starting new work. Unmerged PRs develop painful merge conflicts - pretty quickly, so you'll do much less total work per feature if you're - responsive and try to make it easy for maintainers to merge your commits. - - - (3) Do any relevant follow-ups to larger projects you've completed, to - make sure that you've left things better than how you found them. - - - (4) Starting on the next project. - - - Figure out a QA/testing process that works for you, and be sure to explain - in your PRs how you've tested your changes. Most of the time, in a large - open source project, is spent looking for and fixing regressions, and it - saves everyone time when bugs can be fixed before the code is reviewed, or - barring that, before it's merged. - - - Plan (and if when planning fails, rebase) your branches until they are easy - to merge partially (i.e. merging just the first commit will not make Zulip - worse or break the tests). Ideally, when reviewing a branch of yours, the - maintainer should be able to merge the first few commits and leave comments - on the rest. This is by far the most efficient way to do collaborative - development, since one is constantly making progress, we keep branches - small, and developers don't end up reviewing the easily merged parts of a PR - repeatedly. - - - Look at Steve Howell's closed PRs to get a feel for how to do this well - for even complex changes. - - - Or Eklavya Sharma's (from GSoC 2016) to see a fellow GSoC contributor doing - this well. (`git log -p --author=Eklavya` is a fast way to skim). - - - Team up with other developers close to or in your time zone who are working - on similar areas to trade timely initial code reviews. 75% of the feedback - that the expert maintainers give is bugs/UI problems from clicking around, - lack of tests, or code clarity issues that anyone else in the project should - be able to point out. Doing this well can save a lot of round-trips. - -- Help with code review! Reviewing others' changes is one of the best ways to - learn to be a better developer, since you'll both see how others solve - problems and also practice the art of catching bugs in unfamiliar code. - - - It's best to start with areas where you know the surrounding code - and expertise, but don't be afraid to open up the code in your - development environment and read it rather than trying to - understand everything from the context GitHub will give you. Even - Tim reads surrounding code much of the time when reviewing things, - and so should you :). - - - It's OK to review something that's already been reviewed or just post a - comment on one thing you noticed in a quick look! - - - Even posting a comment that you tried a PR and it worked in your development - environment is valuable; you'll save the next reviewer a bit of time - verifying that. - - - If you're confused by some code, usually that's because the code is - confusing, not because you're not smart enough. So speak up when you notice - this! Very frequently, this is a sign that we need to write more - docs/comments or (better, if possible!) to make the code more - self-explanatory. - -- Plan your approach to larger projects. Usually, when tackling something big, - there's a few phases you want to go through: - - - Studying the subsystem, reading its docs, etc., to get a feel for how things - work. Often a good approach is to fix some small bugs in the area to warm - your knowledge up. - - - Figure out how you'll test your work feature, both manually and via - automated tests. For some projects, can save a lot of hours by doing a bit - of pre-work on test infrastructure or `populate_db` initial data - to make it easy for both you and code reviewers to get the state - necessary to test a feature. - - - Make a plan for how to create a series of small (<100LOC) commits that are - each safely mergeable and move you towards your goal. Often this ends up - happening through first doing a hacky attempt to hooking together the - feature, with reading and print statements as part of the effort, to - identify any refactoring needed or tests you want to write to help make sure - your changes won't break anything important as you work. Work out a fast and - consistent test procedure for how to make sure the feature is working as - planned. - - - Do the prerequisite test/refactoring/etc. work, and get those changes - merged. - - - Build a mergeable version of the feature on top of those refactorings. - Whenever possible, find chunks of complexity that you can separate from the - rest of the project. - -- Spend time every week thinking about what could make contributing to Zulip - easier for both yourself and the next generation of Zulip developers. And then - make those ideas reality! - -- Add Zulip to your resume on [LinkedIn](https://www.linkedin.com/company/zulip-project). - -- Have fun! Spending your summer coding on open source is an amazing life - opportunity, and we hope you'll have a blast. With some luck and hard work, - your contributions to the open source world this summer will be something you - can be proud of for the rest of your life. - -## What makes a successful summer - -Success for the contributor means a few things, in order of importance: - -- Mastery of the skills needed to be a self-sufficient and effective open source - developer. Ideally, by the end of the summer, most of the contributor's PRs should - go through only a couple rounds of code review before being merged, both in - Zulip and in any future open source projects they choose to join. - Our most successful contributors end up as the maintainer for one or - more areas within Zulip. - -- The contributor has become a valued member of the Zulip community, and has made - the Zulip community a better place through their efforts. Reviewing PRs, - helping others debug, providing feedback, and finding bugs are all essential - ways to contribute beyond the code in your own project. - -- Zulip becoming significantly better in the areas the contributor focused on. The - area should feel more polished, and have several new major features the - contributor has implemented. That section of code should be more readable, - better-tested, and have clearer documentation. - -## Extra notes for mentors - -- You're personally accountable for your contributor having a successful summer. If - you get swamped and find you don't have enough time, tell the org admins so - that we can make sure someone is covering for you. Yes, it sucks when you - can't do what you signed up for, but even worse is to not tell anyone and thus - prevent the project from finding a replacement. - -- Mentors are expected to provide on the mentors stream a **brief report - weekly** on (1) how your contributors' projects are going, (2) what (if anything) - you're worried about, and (3) what new things you'd like to try this week to - help your contributor. A great time to do this is after a weekly scheduled call - with your contributor, while your recollection of the state is fresh. - -- Timely feedback is more important than complete feedback, so get a fast - feedback cadence going with your contributor. It's amazing how useful just 5 - minutes of feedback can be. Pay attention to the relative time zones; if you - plan it, you can get several round trips in per day even with big time zone - differences like USA + India. - -- What exactly you focus on in your mentorship will vary from week to week and - depend somewhat on what the contributor needs. It might be any combination of - these things: - - - Helping the contributor plan, chunk, and prioritize their work. - - - Manually testing UI changes and helping find bugs. - - - Doing code review of your contributor's work - - - Providing early feedback on visual and technical design questions. - - - Helping the contributor figure out how to test their changes. - - - Helping the contributor break their PRs into reviewing chunks. - - - Making sure busy maintainers like Tim Abbott provide any necessary feedback - so that the contributor's project doesn't get stuck. - - - Helping with the technical design of projects and making sure they're aware - of useful and relevant reference materials. - - - Pair programming with the contributor to help make sure you share useful tricks. - - - Emotional support when things feel like they aren't going well. diff --git a/docs/index.md b/docs/index.md index ba04439aff..6242812e74 100644 --- a/docs/index.md +++ b/docs/index.md @@ -133,6 +133,16 @@ maxdepth: 3 --- translating/index +``` + +(outreach)= + +```{toctree} +--- +maxdepth: 3 +--- + +outreach/index Index ``` diff --git a/docs/outreach/apply.md b/docs/outreach/apply.md new file mode 100644 index 0000000000..8943a13e39 --- /dev/null +++ b/docs/outreach/apply.md @@ -0,0 +1,188 @@ +# How to apply + +This page should help you get started with applying for an outreach program +with Zulip. + +We try to make the application process as valuable for the applicant as +possible. Expect high-quality code reviews, a supportive community, and +publicly viewable patches you can link to from your resume, regardless of +whether you are selected. + +## Application criteria + +We expect applicants to have experience with the technologies relevant +to their project, or else have strong general programming +experience. If you are just getting started learning how to program, +we recommend taking time to learn the basics (there are many great +online materials available for free!), and applying in the next +program cycle. + +In addition to the requirements of the specific outreach program +you're applying to, successful applicants are expected to demonstrate +the following: + +1. **Ability to contribute to a large codebase.** Accepted applicants + generally have five or more merged (or nearly merged) pull + requests, including at least a couple involving significant + complexity. The quality of your best work is more important than + the quantity, so be sure to [follow our coding + guidelines](../contributing/code-style.md) and [self-review your + work](../contributing/code-reviewing.md#reviewing-your-own-code) + before submitting it for review. + +2. **Clear communication.** Building open-source software is a collaborative + venture, and effective communication is key to making it successful. Learn + how to [ask great questions](../contributing/asking-great-questions.md), and + explain your decisions clearly [in your commit + messages](../contributing/version-control.md#commit-discipline) and [on your + pull requests](../contributing/reviewable-prs.md). + +3. **Improvement in response to feedback.** Don't worry if you make + mistakes in your first few contributions! Everyone makes mistakes + getting started — just make sure you learn from them! + +We are especially excited about applicants who: + +- Help out other applicants + +- Try to solve their own obstacles, and then [ask well-formed + questions](/contributing/asking-great-questions) + +- Develop well thought out project proposals + +Starting in 2022, being a student is not required in order to apply to +GSoC. We are happy to accept both student and non-student GSoC +participants. + +## Getting started + +If you are new to Zulip, our [contributor +guide](../contributing/contributing.md) is the place to start. It +offers a detailed walkthrough for submitting your first pull request, +with many pointers to additional documentation, and tips on how to get +help if you need it. + +We recommend taking the following steps before diving into the issue tracker: + +- Join the [Zulip development + community](https://zulip.com/development-community/), and introduce yourself + in the stream for the program you are participating in. Before you jump in, be + sure to review the [Zulip community + norms](https://zulip.com/development-community/). + +- Follow our instructions to [install the development + environment](../development/overview.md), getting help in [#provision + help](https://chat.zulip.org/#narrow/stream/21-provision-help) if needed. + +- Familiarize yourself with [using the development + environment](../development/using.md). + +- Go through the [new application feature + tutorial](../tutorials/new-feature-tutorial.md) to get familiar with how the + Zulip codebase is organized, and how to find code in it. + +As you are getting started on your first pull request: + +- Read the [Zulip guide to Git](../git/overview.md). It's especially important + to master using `git rebase`, so that you can restructure your commits. You can + get help in [#git help](https://chat.zulip.org/#narrow/stream/44-git-help) if + you get stuck. + +- To make it easier to structure your PRs well, we recommend installing a + [graphical Git client](../git/setup.md#get-a-graphical-client). + +- Construct [coherent, mergeable + commits](../contributing/version-control.md#commit-discipline), with clear + commit messages that follow the [Zulip commit style + guide](../contributing/version-control.md#commit-messages). More broadly, clear + communication on your pull request will make your work stand out. + +- Carefully follow our [guide to reviewing your own + code](../contributing/code-reviewing.md) before asking anyone else for a + review. Catching mistakes yourself will help your PRs be merged faster, and + folks will appreciate the quality and professionalism of your work. + +Our documentation on [what makes a great Zulip +contributor](../contributing/contributing.md#what-makes-a-great-zulip-contributor) +offers some additional advice. + +## Putting together your application + +### What to include + +In addition to following all the instructions for the program you are applying +to, your application should describe the following: + +- Why you are applying: + - Why you're excited about working on Zulip. + - What you are hoping to get out of your participation in the program. + - How you selected your project. +- Relevant experience: + - Summary of your **prior experience with the technologies** used by Zulip. + - Your **prior contributions to open-source projects** (including pull requests, bug + reports, etc.), with links. + - Any other **materials which will help us evaluate how you work**, such as + links to personal or school projects, along with brief descriptions. +- Your **contributions to Zulip**, including pull requests, bug reports, and helping + others in the development community (with links to all materials). +- A **project proposal** (see below). + +**A note for Outreachy applicants**: It is not practical for us to individually +help you develop a specific timeline for your application. We expect you to +submit a project proposal as described below, and will help you manage the +timeline for your project if your application is selected. + +### Project proposals + +Your first priority during the contribution period should be figuring out how to +become an effective Zulip contributor. Start developing your project proposal +only once you have experience with iterating on your PRs to get them ready for +integration. That way, you'll have a much better idea of what you want to work +on and how much you can accomplish. + +As [discussed in the guide to having an amazing experience during the +program](./experience.md#what-about-my-proposal): + +> We have a fluid approach to planning, which means you are very unlikely to end +> up working on the exact set of issues described in your proposal. Your proposal +> is not a strict commitment (on either side). + +Your proposal should demonstrate your thoughtfulness about what you want to work +on, and consideration of project complexity. We will evaluate it based on the +following criteria: + +- Does it give us a good idea of what areas of Zulip you are most excited to + work on? +- Does it demonstrate some familiarity with the Zulip codebase, and reflection + on what makes for a coherent project that is well-aligned with your interests + and skill set? +- Does it demonstrate your ability to put together a reasonable plan? Have you + thought carefully about the scope of various pieces of your project and their + dependencies? Are you taking into account the fact that there can be a lot of + time in software development between having an initial prototype and merging + the final, fully reviewed and tested, version of your code? +- Are you proposing a project that would make a significant positive impact on the + areas you plan to focus on? + +Regardless of which program you are applying to, you can use the [GSoC project +ideas list](./gsoc.md#project-ideas-by-area) as a source of inspiration for +putting together your proposal. + +### Circulating your application for feedback + +We highly recommend posting a rough draft of your application at least one week +before the deadline. That way, the whole development community has a chance to +give you feedback and help you improve your proposal. + +- If you do not have a complete draft ready, at a minimum, we recommend posting + your **project proposal**, along with **your contributions to Zulip** for + context. + +- Please post a link to your draft in the Zulip development community + stream dedicated to your program (e.g., + [#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) or + [#Outreachy](https://chat.zulip.org/#narrow/stream/391-Outreachy)). Use + `Your name - project proposal` as the topic. + +- We recommend linking to a draft in an app that works in the browser and allows + commenting, such as Dropbox Paper or Google Docs. diff --git a/docs/outreach/experience.md b/docs/outreach/experience.md new file mode 100644 index 0000000000..5779c83a89 --- /dev/null +++ b/docs/outreach/experience.md @@ -0,0 +1,327 @@ +# How to have an amazing experience + +If you are joining Zulip as part of an outreach program (e.g. +[GSoC](https://summerofcode.withgoogle.com/) or +[Outreachy](https://www.outreachy.org/)), welcome! Please make sure you read +this page carefully early on, and we encourage you to come back to it over the +course of the program. + +## Your goals + +Your experience as a Zulip outreach program participant is your +responsibility, and we strongly encourage you take full ownership. The +more care, attention, and energy you put in, the more you'll be able +to get out of the program. We're here to support you, but the journey +is yours to make! + +The following are the main goals we'll be guiding you towards, as they are +shared by the great majority of program participants, and are aligned with the +objectives for our umbrella programs. If you have additional goals in mind for +your experience, please let your mentor and the community know, so that we can +help you along. + +- You should gain mastery of the skills needed to be a self-sufficient and + effective open-source developer. By the end of the program, all but the most + complex PRs should ideally go through only a couple of rounds of code review + before being merged. Our most successful contributors gain the expertise to + become a maintainer for one or more areas within Zulip. + +- You should become a valued member of the Zulip community, who works to make it + better for all involved. Reviewing PRs, helping others debug, providing + feedback, and finding bugs are wonderful ways to contribute beyond the code in + your own project. + +- You should feel proud of the significant positive impact you've made on the + areas you focused on. Your areas should be more polished, and have several + new major features that you have implemented. The sections of code you worked + on should be more readable, better-tested, and have clearer documentation. + +Don't forget to have fun! Spending a few months coding on open source is an +amazing opportunity, and we hope you'll have a blast. Your acceptance to the +program means that we we are confident that if you put in the effort, your +contributions to the open source world will be something you can be proud of for +the rest of your life. + +## You and your mentor + +Zulip operates under a **group mentorship** model. Every participant in a Zulip +mentorship program will: + +- Have an assigned mentor, who will be their go-to for personal questions and + concerns, and a consistent point of contact throughout the program. + +- Receive lots of feedback and mentorship from others in the Zulip development + community, in code reviews on pull requests, and by posting + [questions](../contributing/asking-great-questions.md) and ideas in public + streams. + +Mentors and contributors should stay in close contact. We recommend setting up a +weekly check-in call to make sure you stay on track and have a regular +opportunity to ask your mentor questions and get their feedback. Talk with your +mentor about the status of your projects, and get their advice on how to make +progress if some project feels stuck. + +Bring up problems early, whether technical or otherwise. If you're stressed +about something, mention it your mentor immediately, so they can help you solve +the problem. If you're stressed about something involving your mentor, bring it +up with an organization admin. + +## Communication and check-ins + +Communicating proactively with your mentor, your peers, and the rest of the +Zulip community is vital to having a successful mentorship program with Zulip. +It's how we can help you make sure you're working on a great set of impactful +issues, and not getting stuck or taking an approach that won't work out. + +A key communication tool we use is posting regular public check-ins, which are +a required part of the program. We recommend reading your peers' check-ins +to get a feel for what they are working on and share ideas! + +### Getting feedback and advice + +We strongly encourage all Zulip contributors to post their questions and ideas +in public streams in the [Zulip development +community](https://zulip.com/development-community/). When you post in a public +stream, you give everyone the opportunity to help you out, and to learn from +reading the discussion. + +Examples of topics you might ask about include: + +- Making a technical decision while solving the issue. + +- Making a product decision, e.g., if the issue description does not address some + details, or you've identified a problem with the plan proposed in the issue. + +- Making a design decision, e.g., if you have a couple of different ideas and + aren't sure what looks best. + +See our guide to [asking great +questions](../contributing/asking-great-questions.md) for detailed advice on how +to ask your questions effectively. + +### How to post your check-ins + +A check-in is a regular update that you post in the Zulip development community. +You can find many examples in the +[#checkins](https://chat.zulip.org/#narrow/stream/65-checkins) and +[#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) streams. + +- **Frequency**: _Regular check-ins are a required for all program + participants._ If you are working 20+ hours per week, post a check-in at least + twice a week, e.g., Tuesday and Friday. If you are working less than 20 hours + per week, post a check-in at least once a week. + +- **Where to post**: Unless your mentor or program administrator requests + otherwise, post your check-ins in the stream for your program + (e.g., [#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) or + [#Outreachy](https://chat.zulip.org/#narrow/stream/391-Outreachy)), using your + name as the topic. + +- **What to include** in each check-in: + + - The **status** of each ongoing project, e.g., in progress, awaiting feedback, + addressing review feedback, stuck on something, blocked on other work, etc. + To make your update easy to read, include brief descriptions of what you're + working on, not just issue/PR numbers. + + - For projects where you are waiting on feedback, what **type of feedback** is + needed (e.g. product review, next round of code review after initial + feedback has been addressed, answer to some question, etc.). Use [silent + mentions](https://zulip.com/help/mention-a-user-or-group#silently-mention-a-user) + to indicate whose feedback is required, if you think you know who it should + be. + + - Any questions or problems you **feel stuck** on. If there's an ongoing thread + elsewhere, please link to it. Please post each question/problem in a + separate message to make it convenient to quote-and-reply to address it. + Note that discussions about your work will happen in all the usual places + (#**frontend** , #**backend** , #**design** , etc.), and those are the + streams where you should be _starting_ conversations. Your check-ins are a + place to point out where you're feeling stuck, e.g., there was some + discussion in a stream or on GitHub, but it seems to have petered out + without getting to a decision, and you aren't sure what to do. + + - What you've been **actively working** on since your last check-in. + + - What you **intend to focus** on until your next check-in. Indicate if you are + unsure and would appreciate some suggestions or feedback on your plan. + +## Peer reviews + +Reviewing others' changes is one of the best ways to learn to be a better +developer, since you'll both see how others solve problems and also practice the +art of catching bugs in unfamiliar code. As discussed in the [code review +guide](../contributing/code-reviewing.md): + +> Doing code reviews is a valuable contribution to the Zulip project. It’s also +> an important skill to develop for participating in open-source projects and +> working in the industry in general... Anyone can do a code review – you don’t +> have to have a ton of experience. + +For programs with multiple participants, we will set up a **code review buddies** +system at the start of the program: + +1. Everyone will be assigned to a group of 2-3 people who will be your buddies + for first-round code reviews. (In some cases, your buddy will be your + mentor.) + +2. Start by [self-reviewing your own code](../contributing/code-reviewing.md). + +3. When ready, request a review from your code review buddies. Use [GitHub's + review request + feature](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) + to send your request. This makes the PR's status clear to project maintainers. + You may also want to send a quick private message to let your buddies know + their attention is needed. + +4. Please respond to code review requests promptly (within one workday), and + follow the guidelines [in the code review + guide](../contributing/code-reviewing.md). + +Your initial reply does not have to be a full review. If you’re pressed for +time, start by quickly sharing your initial thoughts or feedback on the general +direction, and let the PR author know when you expect to provide a more detailed +review. + +Make sure the GitHub comments on the PR are always clear on the status -- e.g. +buddy code review has been requested, feedback is being discussed, code buddy +has approved the PR, etc. This will help project maintainers know when it's time +to move on to the next step of the review process. + +## How do I figure out what to work on? + +Our goal is for contributors to improve their skills while making meaningful +contributions to Zulip. We like to be flexible, which means that you are +unlikely to work precisely on the issues described in your proposal, and that's +OK! + +In practice, this means that over the course of the program, you will: + +- Get frequent guidance regarding what to work on next by posting your ideas and + questions about what to tackle next in your + [check-ins](#how-to-post-your-check-ins). + +- Like other Zulip contributors, [claim + issues](../contributing/contributing.md#claiming-an-issue) only when you + actually start work on them. + +If someone else fixes an issue you were planning to fix, don't worry about it! +Consider [reviewing their work](../contributing/code-reviewing.md) to build your +expertise in the subsystem you're working on. + +### Prioritization + +Always keep the following order of priorities in mind: + +1. Your top priority should be **fixing any regressions you introduced** with + recently merged work. + +2. **Review others' pull requests** promptly. As you'll experience yourself, getting quick + feedback on your PR helps immensely. As such, if you are asked to review a + PR, aim to provide an initial reply within one workday. + +3. If any of your PRs are actively undergoing review or are marked as + "integration review" ready, be sure to **rebase** them whenever merge + conflicts arise. + +4. Next, prioritize **responding to code review feedback** over starting new + work. This helps you and your reviewers maintain context, which makes it + easier to make progress towards getting your work integrated. + +5. Do any relevant **follow-ups to larger projects** you've completed, to make sure + that you've left things better than how you found them. + +6. Finally, if all of the above are in good shape, **find a new issue** to pick up! + +### What about my proposal? + +We have a fluid approach to planning, which means you are very unlikely to end +up working on the exact set of issues described in your proposal. Your proposal +is not a strict commitment (on either side). + +In terms of managing your work: + +- Regardless of whether an issue was mentioned in your proposal, make + sure you bring it up in your check-ins when you plan to start + working on something. Project priorities shift over time, and we + may have suggestions for higher-priority work in your area of + interest, or issues that will serve as good preparation for other + work you are excited about. It's also possible that a project idea + is not ready to be worked on, or needs to be sequenced after other projects. + +- When asking for recommendations for what to work on next, it's helpful to + include a reminder of what areas you're most excited about, especially early + on in the program when we're still getting to know you. Do not expect program + administrators to remember what issues were listed in your proposal. + +While some program participants stick closely to the spirit of their proposal, +others find new areas they are excited about in the course of their work. You +can be highly successful in the program either way! + +### Tips for finding issues to pick up + +- Look for, claim, and fix bugs to help keep Zulip polished. Bugs and polish + make a huge difference to our users' experience. If you can fix a + [high-priority + bug](https://github.com/zulip/zulip/issues?page=2&q=is%3Aopen+is%3Aissue+label%3Abug+label%3A%22priority%3A+high%22) + in an area you've been working on, it is likely to have more impact than any + new feature you might build. + +- If you're working on something other than the Zulip server / web app codebase, + follow your project on GitHub to keep track of what's happening. + +- The Zulip server / web app project is too active to follow, so instead we + recommend joining [Zulip's GitHub teams](https://github.com/orgs/zulip/teams) + that relate to your projects and/or interests. When an area label is added to + an issue or PR, [Zulipbot](https://github.com/zulip/zulipbot) automatically + mentions the relevant teams for that area, subscribing all team members to the + issue or PR thread. + +### Staying productive + +Here are some tips for making sure you can always be productive, even when +waiting for a question to be answered or for the next round of feedback on a PR: + +- You should be working on multiple issues (or parallelizable parts of a large + issue) at a time. That way, if you find yourself blocked on one project, you + can always push on a different one in the meantime. + +- It can help to plan a bit in advance by thinking about the issue you intend to + pick up next. Are there decisions that will require input from others? Try to + start the conversation a few days before you need an answer. + +- If you are waiting for some decision to be finalized, consider doing + preparatory refactoring that will make the feature easier to complete and can + already be merged. + +## How else can I contribute? + +- Participate and be helpful in the community! Helping a new contributor get + started or answering a user's question are great ways to contribute. + +- Test and give feedback on new features that are deployed in the development + community! It's fun, and it helps us find bugs before they reach our users. + +- As you are doing your work, keep thinking about what could make contributing to Zulip + easier for both yourself and the next generation of Zulip contributors. And then + make those ideas reality! + +## Timeline extensions for GSoC + +Starting in 2022, it became possible to extend the timeline of a GSoC project. +This can be a great idea if you don't have a lot of time to dedicate each week, +or have an interruption during the program (e.g., getting sick, travel, family +obligations, etc.). + +We're generally very flexible, so if extending your project dates would make it +less stressful to put in the required hours, please discuss this with your +mentor and Zulip's GSoC administrator. Please start this conversation +proactively as soon as you realize that you might need an extension, as this +will give us confidence that you'll be able to manage your time effectively to +successfully complete the program. + +It is possible to have the midterm evaluation happen more than half-way through +the project timeline. If the balance of hours you plan to spend on GSoC is +significantly weighted towards the latter half of your GSoC contribution period, +please contact Zulip's program administrator to discuss pushing out the midterm +evaluation. diff --git a/docs/contributing/gsoc.md b/docs/outreach/gsoc.md similarity index 63% rename from docs/contributing/gsoc.md rename to docs/outreach/gsoc.md index 31703c8cd0..ee985b5f08 100644 --- a/docs/contributing/gsoc.md +++ b/docs/outreach/gsoc.md @@ -1,231 +1,30 @@ -# Google Summer of Code +# GSoC project ideas -## About us +This page describes ideas you can use as a starting point for your project +proposal. If you have not done so yet, you should **start by reading our [guide on +how to apply](./apply.md)** to a Zulip outreach program. As noted in the guide: -[Zulip](https://zulip.com) is the only modern team chat app that is ideal for both -live and asynchronous conversations. Zulip has a web app, a cross-platform -mobile app for iOS and Android, cross-platform desktop and terminal apps, and -over 100 native integrations. The entire Zulip codebase is 100% open source. +> Your first priority during the contribution period should be figuring out how +> to become an effective Zulip contributor. Start developing your project proposal +> only once you have experience with iterating on your PRs to get them ready for +> integration. That way, you'll have a much better idea of what you want to work +> on and how much you can accomplish. -Zulip has been gaining in popularity since it was [released as open source -software][oss-release] in late 2015, with code contributions from [over 1000 -people](https://zulip.com/team) from all around the world. Thousands of people -use Zulip every day, and your work on Zulip will have meaningful impact -on their experience. +## Project size and difficulty -[oss-release]: https://blogs.dropbox.com/tech/2015/09/open-sourcing-zulip-a-dropbox-hack-week-project/ - -As an organization, we value engaged, responsive mentorship and making sure our -product quality is extremely high. You can expect to receive disciplined code -reviews by highly experienced engineers. Since Zulip is a team chat product, -your GSoC experience with the Zulip project will be highly interactive. - -> _“The experience of working with Zulip for the summer was really phenomenal and -> taught me a lot about software development and working with a community. Zulip -> has one of the best open source communities out there who are super friendly -> and welcoming. You learn a lot just by watching others work and talk.”_ – Sai -> Rohitth Chiluka, Zulip GSoC 2021 participant - -As part of our commitment to mentorship, Zulip has over 160,000 words of -[documentation for -developers](../index.md#welcome-to-the-zulip-documentation), much of it -designed to explain not just how Zulip works, but why Zulip works the way that -it does. To learn more about our mission and values, check out [this blog -post](https://blog.zulip.com/2021/04/28/why-zulip-is-on-github-sponsors/)! - -## The Zulip GSoC experience - -Zulip has been a GSoC mentoring organization since 2016, and we accept 15-20 -GSoC participants each summer. We have also mentored several interns through the -[Outreachy](https://www.outreachy.org/) program, and hundreds of Google Code-In -participants. - -Zulip operates under a **group mentorship** model. While you will have an -assigned mentor, you will also get lots of feedback from other members of the -[Zulip development community](https://zulip.com/development-community/) by -posting your questions and ideas in public streams. We encourage GSoC -participants to help each other out as well! - -Many GSoC participants stay involved with the project past the official end of -the program. A number of folks who get started with GSoC go on to mentor the -next cohort of participants, and several have joined Zulip's team of core -maintainers. - -To learn more about the experience of doing GSoC with Zulip, check out our -[Zulip's Google Summer of Code 2021 blog -post](https://blog.zulip.com/2021/09/30/google-summer-of-code-2021/). Our [guide -for having a great summer with Zulip](summer-with-zulip.md) will -also give you a feel for what it's like to do GSoC with us. - -> _“It has been the best summer I've ever had! I'm thankful to my mentors, my -> peers, Zulip, and Google for providing me an opportunity of getting involved -> in the community! You have helped and supported me to become a better software -> developer and a passionate open-source contributor.”_ – Sarthak Garg, Zulip -> GSoC 2021 participant - -## Getting started - -We have an easy-to-set-up development environment, and a library of -tasks that are great for first-time contributors. Use -[our first-time Zulip developer guide](contributing.md#your-first-codebase-contribution) -to get your Zulip development environment set up and to find your first issue. If you have any -trouble, please speak up in the -[#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) stream on the -[Zulip development community server](https://zulip.com/development-community/) -(use your name as the topic). - -## Application tips, and how to become a strong candidate - -Zulip has some of the highest standards of any GSoC organization. The most -important component of a strong application is to demonstrate your ability to -contribute to a large codebase. Accepted applicants generally have five or more -merged (or nearly merged) pull requests, including at least a couple of -significant changes (on the order of 100+ lines). - -The quality of your best work is more important than the quantity, so be -sure to follow our coding guidelines and test your work before submitting it for -review. Don't worry if you make mistakes in your first few -contributions! Everyone makes mistakes getting started — just make sure you don't -make the same mistakes next time. - -It's best to get started with Zulip early, so that you have time to learn, make -contributions, and put together a strong proposal. However, we recommend waiting -until the last few weeks to formally write up and submit your application. - -The GSoC 2022 application deadline is April 19, 2022. Please follow [GSoC's application process -instructions](https://google.github.io/gsocguides/student/). Your application should include the following: - -- Details on any experience you have related to the technologies used - by Zulip, or related to our product approach. -- Links to materials which help us evaluate your level of experience and - how you work, such as personal projects of yours, including any - existing open source or open culture contributions you've made and - any bug reports you've submitted to open source projects. -- Some notes on what you are hoping to get out of your project. -- A description of the project you'd like to do, and why you're - excited about it. -- Some notes on why you're excited about working on Zulip. -- A link to your initial contribution(s). - -We expect applicants to either have experience with the technologies -relevant to their project or have strong general programming -experience. We also expect applicants to be excited about learning -how to do disciplined, professional software engineering, where they -can demonstrate through reasoning and automated tests that their code -is correct. - -For all of our projects, an important skill to develop is a good -command of Git; read [our Git guide](../git/overview.md) in full to -learn how to use it well. Of particular importance is mastering using -`git rebase` so that you can construct commits that are clearly correct -and explain why they are correct. We highly recommend investing in -learning a [graphical Git client](../git/setup.md) and learning to -write good commit structures and messages; this is more important than -any other single skill for contributing to a large open source -project like Zulip. - -We are excited about candidates who submit good contributions to Zulip projects, -help other applicants on [GitHub](https://github.com/zulip/zulip) and on -[chat.zulip.org](https://zulip.com/development-community), learn from our -suggestions, [try to solve their own obstacles and then ask well-formed -questions](https://www.mattringel.com/2013/09/30/you-must-try-and-then-you-must-ask/), -and develop well thought out project proposals. - -For the first time in 2022, being a student is not required in order to apply to -GSoC. We are happy to accept both student and non-student participants. - -Our documentation on [what makes a great Zulip -contributor](contributing.md#what-makes-a-great-zulip-contributor) -offers some additional helpful information. We also recommend reviewing the -[official GSoC -resources](https://developers.google.com/open-source/gsoc/resources/), -especially the [Contributor/Student -Guide](https://google.github.io/gsocguides/student/). - -## Questions are important - -A successful GSoC revolves around asking well-formed questions. -A well-formed question helps you learn, respects the person answering, -and reduces the time commitment and frustration level of everyone -involved. Asking the right question, to the right person, in the right -way, at the right time, is a skill which requires a lifetime of -fine-tuning, but Zulip makes this a little bit easier by providing a -general structure for asking questions in the Zulip community. - -This structure saves time answering common questions while still -providing everyone the personal help they need, and maintains balance -between stream discussion and documentation. Becoming familiar and -comfortable with this rhythm will be helpful to you as you interact -with other developers on -[chat.zulip.org](https://zulip.com/development-community). It is always -better (and Zulip’s strong preference) to ask questions and have -conversation through a public stream rather than a private message or -an email. This benefits you by giving you faster response times and -the benefit of many minds, as well as benefiting the community as -other contributors learn from reading the conversation. - -- Stick to the [community norms](https://zulip.com/development-community/). -- Read these three blog posts - - [Try, Then Ask](https://www.mattringel.com/2013/09/30/you-must-try-and-then-you-must-ask/) - - [We Aren’t Just Making Code, We’re Making History](https://www.harihareswara.net/sumana/2016/10/12/0) - - [How to Ask Good Questions](https://jvns.ca/blog/good-questions/) -- Understand [what makes a great Zulip contributor](contributing.md#what-makes-a-great-zulip-contributor) - -This is a typical question/response sequence: - -1. You [try to solve your problem until you get stuck, including - looking through our code and our documentation, then start - formulating your request for - help](https://www.mattringel.com/2013/09/30/you-must-try-and-then-you-must-ask/). -1. You ask your question. -1. Someone directs you to a document. -1. You go read the document to find the answer to your question. -1. You find you are confused about a new thing. -1. You ask another question. -1. Having demonstrated your the ability to read, - think, and learn new things, someone will have a longer talk with - you to answer your new, specific question. -1. You and the other person collaborate to improve the document you - read in step 3. :-) - -As a final note on asking for help, please make use of [Zulip's -Markdown](https://zulip.com/help/format-your-message-using-markdown) -when posting questions; code blocks are nicer for reading terminal -output than screenshots. And be sure to read the traceback before -posting it; often the error message explains the problem or hints that -you need more scrollback than just the last 20 lines. - -## Project ideas - -Once you have several PRs merged (or at least one significant PR merged), you -can start developing a specific project plan. We recommend discussing your ideas -in the [#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) stream in the Zulip -development community, in order to get quick feedback from whoever is online. - -This section contains the seeds of project ideas; you will need to do research -on the Zulip codebase, read issues on GitHub, and talk with developers to put -together a complete project proposal. It's also fine to come up with your own -project ideas. As you'll see below, you can put together a great project around -one of the [area labels](https://github.com/zulip/zulip/labels) on GitHub; each -has a cluster of problems in one part of the Zulip project that we'd love to -improve. +GSoC offers two project size options: 175 hours and 350 hours. We have +designed all our projects to have incremental milestones that can be +completed throughout the program. Consequently, all Zulip projects +described below are compatible with either project size. Of course, +the amount of progress you will be expected to make depends on whether +you are doing a 175-hour or 350-hour project. We don't believe in labeling projects by difficulty, because the level of difficulty is highly dependent on your particular skills. To help you find a great project, we list the skills needed, and try to emphasize where strong skills with particular tools are likely to be important for a given project. -We will never reject a strong applicant because their project idea was -not a top priority. On the flip side, we often reject applicants proposing -valuable projects when we haven't seen compelling work from the applicant. - -More important to us than specific deliverables in a project proposal -is a clear body of work to focus on. E.g., if we see a proposal with 8 -Markdown processor issues, we'll interpret this as an applicant excited -to work on the Markdown processor for the summer, even if the specific -set of 8 issues may not be the right ones to invest in. - -### Focus areas +## Focus areas For 2022, we are particularly interested in GSoC contributors who have strong skills at visual design, HTML/CSS, mobile development, full @@ -239,14 +38,19 @@ the project. Every area of Zulip could benefit from the work of a contributor with strong programming skills, so don't feel discouraged if the areas mentioned above are not your main strength. -### Project size +## Project ideas by area -GSoC offers two project size options: 175 hours and 350 hours. We have -designed all our projects to have incremental milestones that can be -completed throughout the summer. Consequently, all Zulip projects -described below are compatible with either project size. Of course, -the amount of progress you will be expected to make depends on whether -you are doing a 175-hour or 350-hour project. +This section contains the seeds of project ideas; you will need to do research +on the Zulip codebase, read issues on GitHub, and talk with developers to put +together a complete project proposal. It's also fine to come up with your own +project ideas. As you'll see below, you can put together a great project around +one of the [area labels](https://github.com/zulip/zulip/labels) on GitHub; each +has a cluster of problems in one part of the Zulip project that we'd love to +improve. + +**Note: The project ideas on this page are from summer 2022.** In the future, we +will update them with details for 2023. You can expect the updated list to look +similar to what you'll find below. ### Full stack and web frontend focused projects @@ -604,25 +408,3 @@ Experts: Rein Zustand, Steve Howell communities. 175 or 350 hours; medium difficulty. **Skills useful**: Python 3, reading feedback from users, CSS, GitHub Actions. - -## Circulating proposals (March to April) - -If you're applying to GSoC, we'd like you to publicly post a rough draft of -a few sections of your proposal at least one week before the application -deadline. That way, the whole development community has a chance to give you -feedback and help you improve your proposal. - -- **What to post:** Please include (1) Links to your contributions - to Zulip (or other projects), and (2) a paragraph or two explaining - what you plan to work on. -- **How to post:** We generally prefer Dropbox Paper or Google - Docs, since those platforms allow people to look at the text without - having to log in or download a particular app, and you can update the - draft as you improve your idea. -- **How to ask for feedback:** Please post a link to your draft in the - [#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) stream in the [Zulip - development community](https://zulip.com/development-community/). - -Thanks for being interested in Zulip! We're always happy to help volunteers get -started contributing to our open-source project, whether or not they go through -GSoC. We hope to hear from you soon! diff --git a/docs/outreach/index.md b/docs/outreach/index.md new file mode 100644 index 0000000000..c5cf77ef9b --- /dev/null +++ b/docs/outreach/index.md @@ -0,0 +1,13 @@ +# Outreach programs + +```{toctree} +--- +maxdepth: 3 +--- + +overview +apply +experience +gsoc +mentoring +``` diff --git a/docs/outreach/mentoring.md b/docs/outreach/mentoring.md new file mode 100644 index 0000000000..35bb01fbf3 --- /dev/null +++ b/docs/outreach/mentoring.md @@ -0,0 +1,100 @@ +# Mentoring + +Mentoring an outreach program participant is a great way to help bring up the +next generation of open-source contributors and support the Zulip community. The +experience of watching your mentee's skills develop can be truly rewarding, and +we encourage you to give it a try. + +Signing up to mentor means committing to being reliable source of support on your +mentee's open-source journey over the course of the program. By signing up, +you're committing to dedicating roughly 3-5 hours a week to the program. + +Mentors generally have weekly calls with their mentees to answer any questions +and help make sure that everything is on track. You are also expected to help +program administrators keep an eye on your mentee's progress, and flag any +concerns you might have. + +## Who can mentor + +In order to mentor with Zulip, you need to have spent significant time working +on Zulip yourself. You need to be familiar with what it takes to get work +integrated, so that you can help your mentee with this process. We encourage +anyone who has successfully completed a mentorship program with Zulip as a +participant to give mentorship a try! + +Note that you do _not_ need to have any expertise in the part of the +codebase that your mentee is working in. We have seen many successful +mentor-mentee relationships where the mentor was new to the parts of +the codebase that were the focus of the project. + +You also do not need to be a currently active contributor to Zulip. Our +expectations and patterns of getting work done have been quite consistent over +time, and it should be easy for you to catch up on anything that's changed since +you were actively involved. + +## Supporting your mentee + +At the start of the program, please read our [guide](experience.md) for program +participants to understand Zulip's expectations for your mentee. + +What exactly you focus on in your mentorship will vary from week to week, and +will depend on what your mentee needs. It might be any combination of: + +- Helping your mentee plan, chunk, and prioritize their work. + +- [Manually testing](../contributing/code-reviewing.md#manual-testing) UI + changes and helping find bugs or identify corner cases needing + further discussion. + +- Providing early feedback on visual and technical design questions. + +- Helping your mentee figure out how to test their changes. + +- Helping your mentee break their PRs into [coherent + commits](../contributing/version-control.md#commit-discipline). + +- Doing [code review](../contributing/code-reviewing.md) of your + mentee's work. + +- Helping with the technical design of projects and making sure + they're aware of useful and relevant reference materials. + +- Pair programming with your mentee to share useful tricks. + +- Emotional support when things feel like they aren't going well. + +It might seem challenging to review code if you're not an expert on +your mentee’s focus area. Don't let yourself be intimidated! +Reviewing changes to code your don't fully understand is a common +experience in software development, and you can still provide valuable +feedback. + +If you don’t understand something about the changes being made, there +is a good chance others would also find it confusing. Asking your +mentee for an explanation will itself be valuable feedback on what +parts of the PR need to be commented or rewritten in a more clear way. + +## Managing challenges + +We rely on you to proactively flag your concerns to Zulip's program +administrators as early as possible. Situations you should bring up include: + +- Lack of communication from your mentee, e.g., missing a scheduled call, + missing multiple [check-ins](./experience.md#communication-and-check-ins), lack + of response to PR reviews, etc. + +- If your mentee's rate of progress on their projects is not commensurate with + the hours of work they are supposed to be dedicating to the project. + +- If you are not seeing improvement in response to the feedback you give. + +- If your mentee seems to be struggling, deeply frustrated, or otherwise is not + having a good experience with the program. + +- Any significant questions or concerns raised by your mentee that you cannot + resolve, which for some reason your mentee cannot raise directly. + +- If it turns out that cannot dedicate sufficient time to support your mentee + for all or part of the remaining duration of the program. As long as Zulip's + program administrators are informed, we can make sure someone else covers for + you. diff --git a/docs/outreach/overview.md b/docs/outreach/overview.md new file mode 100644 index 0000000000..2dd8bb1ff0 --- /dev/null +++ b/docs/outreach/overview.md @@ -0,0 +1,74 @@ +# Outreach programs overview + +This page describes what it's like to participate in a Zulip outreach program, +such as [Google Summer of Code (GSoC)](https://summerofcode.withgoogle.com/) or +[Outreachy](https://www.outreachy.org/). + +## About Zulip + +[Zulip](https://zulip.com) is the only modern team chat app that is ideal for both +live and asynchronous conversations. Zulip has a web app, a cross-platform +mobile app for iOS and Android, cross-platform desktop and terminal apps, and +over 100 native integrations. The entire Zulip codebase is 100% open source. + +Zulip has been gaining in popularity since it was [released as open source +software][oss-release] in late 2015, with code contributions from [over 1000 +people](https://zulip.com/team) from all around the world. Thousands of people +use Zulip every day, and your work on Zulip will have meaningful impact +on their experience. + +[oss-release]: https://blogs.dropbox.com/tech/2015/09/open-sourcing-zulip-a-dropbox-hack-week-project/ + +As an organization, we value engaged, responsive mentorship and making sure our +product quality is extremely high. You can expect to receive disciplined code +reviews by highly experienced engineers. Since Zulip is a team chat product, +your internship experience with the Zulip project will be highly interactive. + +> _“The experience of working with Zulip for the summer was really phenomenal and +> taught me a lot about software development and working with a community. Zulip +> has one of the best open source communities out there who are super friendly +> and welcoming. You learn a lot just by watching others work and talk.”_ – Sai +> Rohitth Chiluka, Zulip GSoC 2021 participant + +As part of our commitment to mentorship, Zulip has over 160,000 words of +[documentation for +developers](../index.md#welcome-to-the-zulip-documentation), much of it +designed to explain not just how Zulip works, but why Zulip works the way that +it does. To learn more about our mission and values, check out [this blog +post](https://blog.zulip.com/2021/04/28/why-zulip-is-on-github-sponsors/)! + +## Outreach program experience + +Zulip has been a [GSoC](https://summerofcode.withgoogle.com/) mentoring +organization since 2016, and we accept 15-20 GSoC participants each summer. We +have also mentored several interns through the +[Outreachy](https://www.outreachy.org/) program, and hundreds of Google Code-In +participants. + +Zulip operates under a **group mentorship** model. While you will have an +assigned mentor, you will also get lots of feedback from other members of the +[Zulip development community](https://zulip.com/development-community/) by +posting your questions and ideas in public streams. We encourage outreach +program participants to help each other out as well! + +Program participants work on a variety of issues in their areas of interest, +from major features to small bugs. You will see your work integrated into Zulip +throughout the program, and even experience the impact of the changes yourself +in the [development community chat](https://zulip.com/development-community/). + +Many program participants stay involved with the project past the +official end of the program. A number of folks who get started as participants +go on to mentor the next cohort, and several have joined Zulip's team of core +maintainers. + +To learn more about the experience of doing an outreach program with Zulip, +check out our [Zulip's Google Summer of Code 2021 blog +post](https://blog.zulip.com/2021/09/30/google-summer-of-code-2021/). Our [guide +for having an amazing experience with Zulip](experience.md) will also give you a +feel for what it's like to do an internship with us. + +> _“It has been the best summer I've ever had! I'm thankful to my mentors, my +> peers, Zulip, and Google for providing me an opportunity of getting involved +> in the community! You have helped and supported me to become a better software +> developer and a passionate open-source contributor.”_ – Sarthak Garg, Zulip +> GSoC 2021 participant