paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-04 05:53:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Reorganize contribution documentation.

Browse Source 
* 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.
This commit is contained in:
Alya Abbott
2022-09-18 23:38:08 -07:00
committed by Tim Abbott
parent 8dc1368be8
commit 1089a34c86
11 changed files with 870 additions and 544 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
docs/contributing/asking-great-questions.md Normal file
View File

@@ -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.

4
docs/contributing/index.md
View File

@@ -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
```

73
docs/contributing/reviewable-prs.md Normal file
View File

@@ -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.

295
docs/contributing/summer-with-zulip.md
View File

@@ -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.

10
docs/index.md
View File

@@ -133,6 +133,16 @@ maxdepth: 3
---
translating/index
```
(outreach)=
```{toctree}
---
maxdepth: 3
---
outreach/index
Index <https://zulip.readthedocs.io/en/latest/>
```

188
docs/outreach/apply.md Normal file
View File

@@ -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.

327
docs/outreach/experience.md Normal file
View File

@@ -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.

276
docs/contributing/gsoc.md → docs/outreach/gsoc.md
View File

@@ -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!

13
docs/outreach/index.md Normal file
View File

@@ -0,0 +1,13 @@
# Outreach programs
```{toctree}
---
maxdepth: 3
---
overview
apply
experience
gsoc
mentoring
```

100
docs/outreach/mentoring.md Normal file
View File

@@ -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.

74
docs/outreach/overview.md Normal file
View File

@@ -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