GitHub’s Phil Haack hosted a panel on Channel 9 that focused on best practices for open source projects.
The panel saw the participation of four maintainers of open source projects: Carlos Rojas, audience evangelism manager at Microsoft for Latin America; Brian Lagunas, maintainer of the PRISM framework, used to build loosely coupled, maintainable, and testable XAML applications; David Paquette, contributor to several open source projects; and Carlos dos Santos, maintainer of CodeCracker, an analyzer library for C# and VB.
The first topic suggested by Haack to the panelists is what they expect from people that want to contribute to their projects. Lagunas remarked the importance to open an issue as a way to initiate a conversation with the project’s maintainers. Rojas also highlights the importance for any potential contributor of having a look at the list of open issues. A very useful practice related to this, both pointed out, is tagging some existing issues as “up for grabs”, meaning that they can be grabbed by anyone willing to contribute. There is even an up for grabs web site where potential contributors can browse a list of open issues that are “up for grabs” for many open source projects. Dos Santos explained that for him it is important the contributors open bugs, fix them, and generally use the project.
All panelists agree that a practice to avoid altogether is for any contributor to commit/push directly to master. Instead, the correct way of doing this is opening a pull request (PR). Lagunas goes into more detail about this point and mentions that his expectation is that contributors will create their own branch, implement their features/fixes, add the relevant tests, then create the PR. At some point, the PR will run through an integrated filter and if it passes all tests, then a proper review will take place to make sure the changes align with the rest of the project’s guidelines.
To help contributors align with a project’s guidelines, it is always useful to add a CONTRIBUTE.md file to the project’s root, says dos Santos. Haack points out that if a CONTRIBUTE.md file exists, then whenever a pull request is created, GitHub will automatically display a reminder that you should have read it. Lagunas stresses the importance of reading the CONTRIBUTE.md file, because it sometimes contains important information that goes beyond code standards. As an example, in Prism, they require that contributors relinquish the control of the code to the project through a perpetual, irrevocable contributor license agreement. This is particularly important when contributors belong to some corporations, because there is a risk that they will come back and reclaim their IP. More in general, panelists agree that licensing terms and being explicit about them is really important – both for contributors and potential users of your project, chimes in Paquette.
Haack then drives the discussion back to the topic of how to ensureq that a pull request does not break a project. Lagunas mentions appveyor – which is available as a free service to open source projects on the .NET platform – to have every PR automatically built and tested. Haack further remarks that if you do not do anything odd in your GitHub projects, appveyor are usually able to handle all dependencies right.
Another area of interest is documentation. Rojas says that the very minimum documentation that shall be provided is a README.md file. Haack points to Prism’s documentation as a good example of how documentation should be done, with a readme file explaining general things and then getting into details in other files. Rojas also points out that a wiki, another tool that GitHub provides, can be effectively used for documentation.
Then the discussion gets to the topic of culture. One of the problems in the open source community is, at times, inadvertently rude attitudes when contributors do not do the right thing. All panelist agree that it is important to treat contributors nicely and always think that they are trying to help, actually. This is particularly important since it may be the case that a PR is the first open source contribution from some developer and the way the project maintainer handles this communication could shape that person’s future attitude toward open source.
Finally, all panelists agreed that for contributors it is important to try not to be shy, look for something that they might be passionate about and never forget that open source is about collaborating and that many people are really passionate about the projects they maintain and love it when other people do start using them or contributing to them.