BT

Best Practices for Open-source Projects

| by Sergio De Simone Follow 14 Followers on Dec 01, 2015. Estimated reading time: 3 minutes |

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.

Rate this Article

Adoption Stage
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

copyright assignment by Ken Geis

Phil Haack made a statement about copyright assignment being important to make it easier to change a project's license. I think that Brian Lagunas' statement about the risk of an institution trying to retract its contribution were more about having a thoroughly documented process, not specifically about copyright assignment. A CLA, approved with the authority of an institution, is what protects from this situation.

Re: copyright assignment by Sergio De Simone

Thanks, Ken.

Indeed, as you point out, copyright assignment is just one possibility. Alternatively the CLA could grant "an irrevocable license to allow the project maintainer to use the contribution". In both cases, the adopted model should be described in the CLA.

Re: copyright assignment by Sergio De Simone

BTW, I edited the post so that point is more clear and to be more precise about Brian Lagunas speaking of relinquishing control of the code, not necessarily copyright.

Thanks.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

3 Discuss

Login to InfoQ to interact with what matters most to you.


Recover your password...

Follow

Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.

Like

More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.

Notifications

Stay up-to-date

Set up your notifications and don't miss out on content that matters to you

BT