5 Things to Know Before Making Open Source Contributions

Read the Documentation

There are a few essential documents that you must read. These might be .md files, .rst files, or specific pages on the project's website:

• README.md: The file that introduces the project.
• Contribution Guide: This outlines how to contribute to the project, including any formatting or styling rules you need to follow when submitting contributions.
• Code of Conduct: The community's behavior guidelines. Generally, as long as you are not too rude or disrespectful, you should be fine, but it's still important to read through it.

Issue Tracker

Understand what issue tracker the project uses. Common ones include GitHub issues or JIRA. As a beginner, it's typical to start by looking for existing issues to work on. If you need to open an issue, be sure to search first to see if a similar issue has already been opened.

Commits

Check whether the project has specific requirements for commit message formatting. It's a good habit not to write commit messages in a sloppy manner. If there are no special requirements, you can refer to Conventional Commits. The basic format looks like this:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Example:

feat: Add XXX feature.

fix(frontend): Fix XXX bugs.

The most common types are:

• feat: Add new features.
• fix: Bug fixes.
• docs: Documentation only changes.
• refactor: Refactoring. That means it does not change any existing functionalities.
• test: Add or correcting existing tests.
• chore: Miscellaneous tasks; use chore if you don't know how to classify it.

Some projects might have slight variations in their symbols or casing, such as:

[Feat] Add XXX feature.

[Fix][Frontend] Fix XXX bugs.

Additionally, some projects provide pre-commit hooks. If so, follow the instructions to install them.

Some projects require every commit to be sign-offed. For details, please refer to the other tutorial written by me:

The Ultimate Guide to Git for Open-Source Development

Chi-Sheng Liu ・ Aug 15

#git #github #opensource #contribution

Pull Request

Unless there are special circumstances, one Pull Request usually corresponds to one issue. Generally, before you submit a Pull Request, if there is no corresponding issue, you should open an issue first. However, if the project does not strictly enforce this rule, and your Pull Request contains only minor changes, you can also directly submit a Pull Request.

Some Special Terms

Sometimes reviewers leave comments using uncommon abbreviations or terms. Besides understanding them, you can also learn to use these terms, which will make you feel more professional 😂.

• LGTM: Looks good to me. Indicates that the reviewer thinks your code is fine.
• PTAL: Please take a look. A request for someone else to review.
• WIP: Work in progress. Indicates that this PR is not ready yet.
• ditto: Means "same as above".
• nit: Indicates a suggestion for a change that the reviewer considers minor, so you can choose whether to make it or not. For example: nit: Rename this variable to XXX.