[Open Source Community Contributor] sounds like a title reserved for top developers, but is it really that far out of reach? The following share aims to demystify it and make it easier for interested students to participate in community projects.

First of all, it should be clarified that the author of this article is not the original author of a community high profile project, just a top 10 contributor in a 5K + Star, 100+ contributor project (for reference, Vue has fewer than 150 contributors), It’s a small, transparent existence compared to the shining stars in the question “What’s it like to Maintain a Large open source Project?” However, because I only have more than one year of experience, in many aspects and just the entrance of the new students are very similar, so I believe that personal experience can have certain reference value, so I made some summary here. If there is something wrong in the article, please correct dalao.

The following content is mainly divided into the following two parts:

  • Getting started and getting ahead, how you can get involved in the community without knowing anything about programming. And how to collaborate on open source projects through Issue and PR once you have the conditions to contribute.
  • Skills and Summary“, some technical details, and how to use GithubBusiness each other blowCommunication skills.

start

There are three main ways to participate in open source projects, from easy to difficult:

  • Translation document
  • Report a bug
  • Submit code

In the beginning, translating documents is the least difficult. Because you don’t even have to write or run any code, just translate it in the edit page.

Take the MDN document maintained by Mozilla, for example. Like Wikipedia, MDN documents are accessible to all users. For example, an MDN document that describes CSS positioning might look something like this at the top of the page:

mdn-large

Notice Languages and Edit? You can select the desired language in Languages, or add a translation for a new language. If you already have a translation, you can just click Edit to Edit it!

When translating, Mozilla’s rich text editor is divided into left and right sections that can be directly compared:

mdn-editor

Now just click Save and you’ll appear as a contributor to this page! Your changes will also be saved in document history, so check them out before committing. In addition, it is not necessary to save the entire document in one time. If you are halfway to save the document, you can click the “localization in Progress” option at the bottom of the page to add a “translation in progress” sign to the browsing page.

We don’t seem to have written a single line of code in this process, so how does that help? In my opinion, translating documents is a good start because it can:

  • Help you better understand the structure of technical documents in English and lay a good foundation for future communication with other developers. As we’ll mention later, many times you need to document more than one or two lines of code.
  • It’s a great way to practice your writing skills. In the beginning, you may write technical documents that are difficult to translate, but as you become familiar with them, you will make great progress.
  • Get feedback on your contributions quickly. The weight of MDN in Google is not low, through Google in the first page to find your translation content, or quite a sense of achievement.
  • Improve your knowledge of the document’s content. For example, the author began to understand the rich text editing field by moving rich text editor documents in Mozilla. After completing the translation, the basic concepts in this field became clear.

In addition to MDN documentation, the Chinese technical community also has a number of excellent related projects to participate in. This aspect individual participation is not much, do not teach fish to swim.

The advanced

You may soon get to the point where you get bored just translating documents, so it’s time to take a look at the bigger world. Find an active project on Github to get started! For open source projects maintained on Github, there are two main ways to participate: Issue and PR:

Issue

For a medium to large open source project, Issue is mainly used to:

  • Report bugs and ask questions
  • Propose and discuss new features
  • Set Todo goals

Note that many projects have their own Discuz forums or Slack groups, and novice questions like why the install failed can be searched in existing issues and then posted in forums and IM. If you make an Issue casually, you will probably get a reply like Duplicate of # XXX and be shut down. A great reference for new students is The Art of Asking Questions: How to Get Answers Quickly.

Once you Issue a project, your Github contribution for the day will be green and you’ll be able to pin the project on your profile page! It looks like you don’t have to write code either, so it’s not that hard. However, simply making an Issue won’t get you on the project’s contributor list, PR is a must if you want to actually contribute code.

PR

Pull Request, as the name suggests, is asking someone to Pull your code. This is very much in line with the open source workflow: developers fork out their own repository, commit code in their own branch, and then ask the maintainer to incorporate their changes. Generally speaking, it is enough for a PR to do one thing well, and its functions are as follows:

  • Fix the bug
  • Implementing new features
  • Optimize performance
  • Routine updates (documents, dependent versions, etc.)

If a new student wants to contribute PR, he/she can start by focusing on something he/she is good at or is interested in, such as a simple document spelling mistake or an Issue marked “Help Please”.

Github contributions on the same day will be green regardless of whether the PR is merged or not, and contributions on the same day will be green when the PR is merged. If you find a bug that can be fixed in a single line, the process might go something like this:

  1. Make an Issue and contribute +1
  2. So if you factor out PR, your contribution is plus 1
  3. Reply to maintainer’s Review Review with +1 contribution
  4. PR passes, contribution +1

So, just submitting one line of code is enough to green up the contribution graph for four days at most. Also, when maintainers Review or incorporate your PR, their contributions will increase accordingly. If you think about it, the number of contributors to a large project, which can range from a few thousand a year, is not something to look forward to.

skills

The above has just introduced a few basic concepts in open source workflows. When it comes to actual participation, there are a few other tips that you can pay attention to. Here are some of the details.

Problem-oriented source code reading

When it comes time to propose bugfix, new feature, or performance optimization class PR, reading the source code of the framework is basically unavoidable. Of course, we often see articles on source code parsing in the technical community (Redux/Vue/Koa being the most recent example). The authors of these articles certainly have good intentions, but it’s a little sad that many of these articles are relatively poorly read, and most of the authors of these articles are not contributors to these frameworks.

Are we being too impetuous? Why do we need to read the source code? Is it to solve a real problem, or is it just to write a blog to show off your skills? How does it help the reader, or the community, if you just post screenshots of code that look great and translate the comments into Chinese? I have read the source code of this framework or I have fixed the bugs of this framework, which contribute more?

In my opinion, debugging source code with questions is much more rewarding than simply reading it. When you really need to solve a bug, you will truly thinking about calling sequence, the execution of the process, the significance of variables, and then in a breakpoint, logs, and with the help of the error stack, really know how seemingly casual judgment is indispensable, look be like simple place hidden how preset conditions.

From this point of view, maintaining open source projects with the motivation to fix bugs is much more technical than simply reading source code or liking blogs in the technical community. With every developing project, there are a number of discovered and undiscovered bugs waiting to be fixed. By participating, your work will benefit not only the community, but yourself as well.

However, how to read the source code is beyond the scope of this article. It is enough that we leave it at this point.

friendlyEach blowevaluation

One important difference between working on open source projects and moving documents is the interaction with others. Your Issue will get reviewed, your code reviewed, and your PR will get liked. Interaction with other people is essential. At Github, the right way to communicate can be very helpful.

We’ll share just one thing: how to be kinder in judging other people’s work. In the Chinese community, it is not uncommon to see trolls directly attacking the quality of projects or accusing people of plagiarism. However, poking fun at other people’s code is certainly a must. How can you gently point out PR issues or respond to issues when communicating with the community?

It’s funny how rarely you see these words on Github:

bad wrong dirty terrible ***...Copy the code

You can hardly see the following statement:

I think this code is bad and do things wrong!Copy the code

As opposed to making fun of the bad code:

  • Presentation apis are clunky and hard to use, so to speakheavy to work with
  • The presentation module is poorly structured, so to speaknot intuitive
  • Expression processing is too rough, so to speakoverkill
  • The presentation logic can be flawed, so to speakleaky
  • Expression involves too much, so to speakaggressive
  • .

But I think it is very arbitrary.

  • The almightyIMO 或 IMHO, i.e.,In my (humble) opinion
  • Added aNot sure, maybe missing something
  • withTo my knowledgeorFor me

Also, it’s good to remember to include Would you please and Could you please when requesting a Review or merge from other contributors. Don’t forget, Thanks.

All in all, it is very interesting to explore the appropriate vocabulary for communication, but the Requirements for English are not high. In fact, using the above introduction is enough as long as the junior high school English level. I believe that interested students can summarize more [open source slang] 😅 in addition, many projects of Code of Conduct is also worth reading.

Effective communication

The process of contributing to the community is not about throwing code in people’s faces at first, and many Bugfixes require discussions with upstream maintainers before making decisions. In addition to polite words, the way of communication is also important. In this personal summary of the following points:

A questioning rebuttal

Socrates had a way of arguing with people by asking them questions until they couldn’t answer them. This is also common in community communication.

For example, when a PR was thought to have a boundary case that was not considered, as a Reviewer, it would be clever to comment on How is it when XXX rather than directly judging You are missing XXX. You can politely ask the submitter to elaborate on a particular case or change the code, rather than just kill it.

Similarly, I don’t know what you mean at Workaround. Waiting for the other person to explain is better than saying This is wrong.

Pay attention to the description

When submitting an Issue, different descriptions may result in different priorities and different processing results. Here’s a recent example:

In the project we participated in, there was an Issue describing [performance problem], and the content was roughly [the input speed was very slow when the content was large]. This Issue has been suspended for one or two weeks without anyone to deal with it. After debugging, I found a particular scenario where repeated redrawing caused the page to crash. After submitting the Issue with “page dead loop” as the title, the author fixed the Issue the same day, and the performance Issue was also resolved.

Templates and Tools

In fact, many of the above content is a fixed routine to follow. For example, both Issue and PR have relatively fixed templates to help participants improve communication efficiency.

A common template for Issue is something like a syllogism:

  1. Bug or Feature?
  2. Current Behavior?
  3. Expected Behavior?

For PR, it does not need to be long, but the formal structure is roughly:

  1. This Closes #xxx
  2. Current Behavior / Reason
  3. Solution

When submitting an Issue, it is important to provide examples, steps, or GIFs to reproduce. You can use JSFiddle to provide a simple example of replaying, and there are also free GIF recording tools like Giphy Capture on The Mac to help.

Finally, a clean commit record is also a big plus when it comes to Git commits. If you are interested in this topic, please refer to my previous article on Improving PR with Git Rebase.

conclusion

Participating in the open source community can be both challenging and rewarding. Compared with the common recruitment slogan “Your line of code can affect many people” of Domestic Internet companies, contribution to the open source project means that your code can be used by many companies. This is undoubtedly a higher level, and there will be more challenges. If the daily logic of adding, deleting and deleting is getting to you, getting involved in the community might open the door to a new world.

By the way, we are currently maintaining the editor project Slate. This is an excellent and rapidly iterating rich text framework, currently in beta with a lot of new features and functionality, lots of opportunities to contribute, and the source code style and annotations are quite complete. Another interesting point is that the author, like Evan You, has a background as a designer (imagine a bunch of programmers fixing bugs in code written by UI designers). I have also tried Slate in my previous blog. I hope more students can try it!

To conclude this article, let’s use one of the principles of the Chrome V8 project:

In short, do the right thing for the project, not the easiest thing to get code committed, and above all: use your best judgement.