Rules to Better Open Source Software

​​

Hold on a second! How would you like to view this content?
Just the title! A brief blurb! Gimme everything!
  1. Do You Know Open Source Contribution Etiquette? ( a.k.a. don't re-order my house when you fix my tap)

    If you get a tradesman in to fix your tap, and on the way to the kitchen he sees your bookcase is messy and re-orders it for you.... you probably wouldn't be very happy.

    When you contribute to open source projects it is great to fix bugs and contribute features, but it is essential to be respectful of the people that came before you, and possibly have invested lots of time in putting everything where it currently is.

    etiquette-bad.png
    Figure: Bad Example - bad open source contribution etiquette involves gratuitous refactoring, re-organisation of files and classes, changing of formatting beyond those used throughout the rest of the project
    ​​
    etiquette-good.png
    Figure: Good Example - good open source contributors review the CONTRIBUTING.md for the project and work within the guidelines provided, they follow existing coding styles and architecture and if large refactoring or changes are required communicate with the community and the core contributors​​

    This issue is described beautifully here http://tirania.org/blog/archive/2010/Dec-31.html

  2. Do You Know to not 'Push' your Pull Requests? (a.k.a. discuss then build)

    For the original article check out ​​​​​Don't "Push" Your Pull Requests ​b​y Ilya Grigorik.​

    Open source software projects love it when the community get involved and pitch in.

    It's great when someone fixes a bug.​

    A short pull request to fix a small problem is easy to review and accept.

    It's great when someone adds a much-needed feature
    ...as long as the feature fits in with the project the core contributors have for the project
    ...and it meets the existing coding patterns and engineering standards.

    This is where frustration often starts to set in on open source projects.

    A contributor has a great idea for a feature, or identifies an area where they can add value and does so without consulting with the core contributors who have often spent hundreds of hours working on the project.

    Their contribution might solve their problem, but after it has been accepted it will most likely be left for the core contributors to maintain.

    # Poor Communication Contribution

    • developer has good idea for project
    • bashes away and writes 600 lines of code
    • submits pull request
    • core contributor looks at large pull request
      she doesn't fully understand purpose of request / the problem it solves
      she doesn't like that the PR author hasn't followed the existing coding standards
      she makes a push back comment
    Figure: Bad Example - Poor early communication can lead to mis-directed work and pull requests not being accepted

    # Good Communication Contribution

    • developer (PR Author) has good idea for project
    • reviews the list of outstanding issues for the project and confirms that someone hasn't already had the same idea and started a discussion on it
    • author creates an issue on GitHub and outlines the problem they are trying to solve, and outlines their suggested solution
    • the core contributors and other interested parties can help refine both the idea for the feature and the suggested implementation
    • the author can then start working on the feature knowing that their idea for the project complies with the maintainers vision for the project and know it is likely to be merged into the core codebase
    Figure; Good  Example - Good communication leads to collaboration and better outcomes for the author and the project

    # Projects with Internal Teams

    • Internal SSW team members should only work on features during work hours that have been assigned to a release by the core contributors for a project
    • Features will be assigned to a release during the Community Standup
  3. Do you make it clear when a project is no longer maintained?

    It is important that users of your open source contributions are aware if you are maintaining them and keeping them up to date.​
    open-source-retired.png
    Figure: Good Example - It is clear that the project is not going to be updated, and where to go for the most recent version. The description starts with "Retired" , and the readme very clearly indicates that the project has been replaced with a newer version and where to get it

    open-source-retired-2.png
    Figure: Good Example - one off repos. For repositories just created to share code with students, it should be clear that the code will not be updated and maintained, and reference the course associated with its creation

  4. Do You Tell People How To Get Involved with your Project?

    The key to building a great open source project is to build a great community around your project.

    To do this it is essential that potential contributors can find out how to get involved.​

    ​​It is a common pattern for open source projects to contain a CONTRIBUTING.md markdown file that supplies information on how to get involved.​​

    getinvolved1.png
    Figure: Good Example - The Microsoft ASP.NET and Azure teams both do a great job of providing documentation on how to start contributing
    getinvolved2.png
    Figure: Good Example - The ASP.NET team (and the SSW team) use a common CONTRIBUTING.md in a common 'Home' repository. This ensures that all projects for their team are collaborated on in the same way
  5. Do You Tell People the Coding Standards You Expect?

    The code within your solution should be consistent. (We all know that)​

    In an open source project the easy way to ensure that all developers share and are aware of the expectations is to include and ENGINEERING-GUIDELINES.md markdown file that includes important technical considerations like​:

    • Copyright header requirements
    • Approved external dependencies
    • Coding guidelines and standards
    • Source control requirements
    • Branching strategy
    • Solution and project folder structure and naming
    • Unit testing requirements
    guidelines-opensource.png
    Figure: Good Example - Adding an ENGINEERING-GUIDELINES.md to your project clearly defines the engineering practices and guidelines that must be required for contributors pull requests to be accepted