Introduction

Basic Process

  • Choose a project
    • Encountered in work
    • Daily use
    • Familiar with the tech stack used by the project
    • …
  • Identify a problem
    • Code
    • Spelling
    • Documentation
    • Tests
    • …
  • Fork
  • Modify
    • Code
    • Tests
    • Comments
    • Documentation
  • Sign contributor agreement
    • CLA
    • DCO
  • Submit pull request
    • CI
    • Review
    • Merge
  • Follow-up
    • Close issue
    • Wait for release
    • Continuous contribution to become a maintainer

General Principles

How to Be a Qualified Open Source Project Contributor

  • Identify your skills and tech stack, and choose a matching open source project.
  • Understand the code structure, functions, and specifications of the open source project, and read its contribution guidelines.
  • Various types of contributions are welcome, such as fixing bugs, adding features, writing documentation, tests, etc.
  • Start with small changes, such as modifying documentation, spelling, adding test code, fixing bugs with a small scope.
  • Core process: Create and submit a pull request (PR), and wait for reviews and feedback from other contributors.
  • Maintain good communication and collaboration with other contributors.
  • Follow the open source project’s code of conduct.

How Non-Native English Speakers Can Participate Better

  • Improve English proficiency, especially reading and writing skills, to better understand project requirements, documentation, and code, and to clearly express ideas and suggestions.
  • Choose open source projects with active communities and friendly atmospheres to get more help and support, and learn from other contributors’ experiences.
  • Follow the open source project’s contribution process, such as fork, clone, branch, commit, push, and pull request, and abide by the project’s coding style and specifications.
  • When submitting issues or PRs, try to use simple and clear English to describe the problem or feature, and attach relevant screenshots or code snippets.
  • When communicating with other contributors, be polite and respectful, don’t be afraid to ask or answer questions, and respond to their reviews and feedback in a timely manner.
  • If unsure about certain English words or expressions, use dictionaries, translation tools, or grammar checkers to assist communication.

How to Get Open Source Project Maintainers to Quickly Review Your PR

  • Follow project guidelines: Before submitting a pull request, be sure to check and follow the project’s contribution guidelines. Ensure the request meets the project’s specifications and standards.
  • Ensure consistent code style: Follow the project’s code style and formatting requirements to reduce the amount of code that maintainers need to modify during review.
  • Provide detailed description: When submitting a pull request, ensure you provide a sufficiently detailed description explaining how the modification solves the problem or improves the project.
  • Provide test cases: Try to ensure that new code is covered. Some projects check unit test coverage and covered lines.
  • Reply to comments promptly: Once your pull request is reviewed, reply to the maintainer’s comments as quickly as possible and consider the opinions and suggestions discussed.

Github Flow

Difference from Gitlab Flow

Github Flow:

  • Github Flow is a simple workflow, mainly including creating branches, submitting code, sending pull requests, and merging branches. This is a fast iteration process suitable for small teams and agile development.
  • In Github Flow, code is developed on the master branch. Developers create new branches based on master, develop and test features, then send a Pull Request to the main branch, requesting code review and merging the branch into the main branch.
  • Github Flow is suitable for fast iteration and small teams but might be too simple for large projects and may require stricter code review and testing.

GitLab Flow:

  • GitLab Flow is an enhanced version based on Github Flow, more suitable for large, complex projects, offering more automation and process control features.
  • In GitLab Flow, code is developed on feature branches, similar to Github Flow, but it includes an additional stage - the preparation stage, used for automated testing and code review before developers complete feature branches, ensuring code quality and reliability.
  • GitLab Flow manages releases using tags or cherry-picks.

Familiarize with the Project

Open Source License

Open Source Contribution Agreement

  • Open source contribution agreements include CLA (Contributor License Agreement) and DCO (Developer Certificate of Origin);
  • DCO was proposed by the Linux Foundation and consists of fixed short clauses (only 4), aimed at ensuring contributors comply with the open source license;
  • CLA is a legal supplement to the open source license, formulated by legal affairs;
  • CLA can be customized and requires detailed information such as name, company, email, address, phone number, etc., whether signed by individuals or enterprises;

CLA CI Status Example


DCO CI Status Example


Project Structure

src, build, doc, etc.

Project Documentation

  • LICENSE: According to the definition of open source software, every open source project must have an open source license. If a project’s source code is open but has no license, it cannot be called open source.
  • README: README is an introductory file that welcomes people visiting the community for the first time. It usually explains the purpose of the project, why it was started, and how to get started quickly.
  • CONTRIBUTING: The README file helps people understand the project, while the CONTRIBUTING file tells people how to contribute to the project. It explains what types of contributors the project currently needs and what the community process is like. Not all projects have this file, but to some extent, it shows the project’s friendliness towards contributors.
  • CODE_OF_CONDUCT: As the name implies, these are etiquettes, ways of speaking, and behaviors when participating in the community, to form a friendly atmosphere. Not all projects write a code of conduct file, but it also demonstrates friendliness towards contributors.
  • Other Documentation: Some projects may have other documents, such as tutorials, guides, or governance rules, which are common in large projects.

Project Discussion

  • Issues: A place to discuss project-related problems, similar to Jira for internal bug communication in enterprises.
  • Pull requests: Code review and related discussions.
  • Forums or Mailing Lists: Such as Golang, Python, Linux.
  • Instant Chat: Some projects use chat channels (such as Slack, IRC, Gitter) for casual conversation, collaboration, and quick exchange.

CI

  • Github Actions
  • Travis-CI
  • …

Pull Request

Communication

Improving Written English Skills

Machine Translation

  • DeepL
  • Google
  • Bing
  • Baidu
  • Youdao
  • Tencent

English Checking and Correction Tools

  • Grammarly
    • Established grammar checking tool, free + paid model, has Chrome extension, mobile keyboard input method, advanced version is paid.
  • LanguageTool
    • Open source free + paid model, supports more languages than Grammarly, such as Chinese.
  • QuillBot
    • More focused on article polishing.
  • DeepL Write
    • Grammar and article checking tool launched by DeepL Translation.
  • ChatGPT/BingChat
    • Conversational bot, you can command it to write English descriptions or check grammar.

Reference Links: