Suppose that you decided that you want to contribute to a particular project. What are the next steps? For this example, we look at the Visual Studio Code repository at https://github.com/microsoft/vscode.
1. Reading the CONTRIBUTING guide
As the suggestion on the Issues page notes, read through the contributing guidelines first.
The contributing guidelines message displayed on the Issues page is controlled by a convention. Add a file named CONTRIBUTING.md to the root of the repository, a folder named docs, or a folder named .github in order to specify contributing guidelines for a repository.
Visual Studio Code’s contributing guidelines are located at https://github.com/ Microsoft/vscode/blob/master/CONTRIBUTING.md.
Like many contributing guides, the guide provides a high-level overview of how to make contributions to the project. It notes that contribution is more than just writing code. To emphasize that philosophy, the guide starts by letting you know where to ask questions about the project. The guide address the key topics:
» Where to ask questions
» Where to provide feedback
» Where and how to report issues
» Details about their automated issue management
» A link to a guide on how to contribute code
This format is pretty common for contributing guides. Sometimes, a smaller project will also include how to contribute code in the main document, but for larger or more complex projects, contributing code is a big topic.
2. Reading the contributing code guide
The VS Code project keeps its code contribution guide in a wiki located at https:// github.com/Microsoft/vscode/wiki/How-to-Contribute.
REMEMBER: If you plan to contribute code, read through this guide carefully.
The guide has the key information you’ll want to code on the project and is structured in a fashion pretty common among open source projects:
» Building the code
» Running the code
» Debugging the code
» Running the automated tests
» Running automated code analysis, such as linting
The next section covers the code contribution workflow:
» Following the branching strategy
» Creating pull requests
» Packaging code for distribution
3. Reading the code of conduct
The contributing guide focuses on the mechanics of making a contribution. Many projects now also include a CODE_OF_CONDUCT.md file. This file lays out expectations for those who participate in the project. It sets the behavioral norms for the project and a resolution process in cases where violations of the norm occur.
VS Code uses the Microsoft Open Source Code of Conduct located at https:// opensource.microsoft.com/codeofconduct.
TIP: Adding a code of conduct to your own repository is easy. If you add a new file on GitHub using the browser and name the file CODE_OF_CONDUCT.md, GitHub displays a code of conduct selection drop-down list with two choices: the Contributor Covenant and the Citizen Code of Conduct.
You can also visit the community page for any public repository to add a code of conduct. Go to the community page by appending /community to the end of the repository URL. For example, type https://github.com/microsoft/vscode/ community to see w the project has a code of conduct. If it doesn’t, the page gives you the opportunity to propose one.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.