SSW Foursquare

Rules to Better Open Source Software - 9 Rules

  1. Do you use Open Source software?

    3rd party tools are awesome. They give us quick out-of-the-box solutions to common problems saving tonnes of dev time.

    Unfortunately, with traditional 3rd party solutions, you have limited options for making changes to the product. You can send through feedback, but there is no guarantee that the devs will look at it, and even if they do look at it, they might not action it. So, how can we break through this locked system to get the features we want?

    Open Source software is the key to making all your dreams come true 🤩.

    Open Source software is a great option, but it's not always the best. Make sure to consider these points before deciding to use open source software.

    Video: Utilizing Open Source Software with Brady Stroud (3 min)

    ✅ Benefits

    • Transparency - when a bug occurs you can look at the source code and easily find the area where the bug occurs
    • Usually free - there are some paid open source software options
    • Customizable - you can fork and adapt it to your own needs
    • Quality - open source projects have thousands of developers going through the code which ensures quality
    • Security - Any vulnerabilities are public so they are more likely to be noticed and fixed (This also means hackers could fix and exploit vulnerabilities)

    ❌ Downsides

    • Lifespan - Open source projects are more likely to be abandoned
    • Support - Paid software will typically have a support team you can get in touch with if you have issues. For open source software you can create GitHub issues, but there is a chance the repository owners wont respond

    Gotchas

  2. Does your company contribute to open source?

    Open-sourcing software has become increasingly popular for companies as it can help them innovate, attract talent, and build a good reputation. It also helps the community by providing free software that can be used by anyone.

    Some good examples of companies that open source their code are:

    🧱 Collaboration

    Open-sourcing opens your project to a broad range of people with unique skillsets can help accelerate your project's innovation. It also allows you to leverage the work of others to help your project grow.Every time someone submits a PR fixing a bug, you are getting free software development.

    🔗 Networking

    Being a part of the developer community is a great way to discover potential employees. If a developer has been using a company's open source code for years, they are more likely to want to join and keep using that code.

    👨‍🏫 Demonstrate

    Making your code public shows confidence in your service and can be a great oppurtunity to demonstrate your company's skills and practices.

    🤝 Sharing solutions

    Open-sourcing your code doesn't have to mean making your whole project public. You can take small chunks of code and make them generic enough so they're useful to others.
    Examples of this are:

  3. Do you know the open source contribution etiquette? (aka Don't re-order my house when fixing 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-order 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
    Figure: Bad example - Bad open source contribution involves gratuitous refactoring, re-organisation of files and classes, changing of formatting beyond those used throughout the rest of the project

    etiquette good
    Figure: Good example - 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 Open Source Contribution Etiquette by Miguel de Icaza.

  4. Do You Know to not 'Push' your Pull Requests? (aka discuss then build)

    For the original article check out Don't "Push" Your Pull Requestsby 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
  5. 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
    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
    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

  6. 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
    Figure: Good Example - The Microsoft ASP.NET and Azure teams both do a great job of providing documentation on how to start contributing

    getinvolved2
    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

  7. 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
    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

  8. Licensing – Do you know the correct license to use for Open Source software?

    More and more projects are being created as Open Source. However just because you’re created an open source project doesn’t mean you give everything in your cookie jar away. You should only release your code subject to a licence agreement. A common confusion when putting projects onto Open Source platforms like GitHub is ‘What License Should I Use?”. We have our own opinions but we aren’t lawyers so if you want to know what’s best for you speak with your lawyer.

    license bad
    Figure: Bad Example - No License - Generally speaking, the absence of a license means that default copyright laws apply. This means that you retain all rights to your source code and that nobody else may reproduce, distribute, or create derivative works from your work. For more information read http://choosealicense.com/no-license/

    license good
    Figure: Good Example - GPL License – For projects where you want consumers of your code to share their changes. Anyone who distributes your code or a derivative of your code must make the source available under the same terms. Warning: Consider carefully before using on components to be used in commercial applications due to the CopyLeft requirement. Used by Linux, Git, WordPress - GNU General Public License on Wikipedia

    license good 2
    Figure: Good Example - MIT License - for projects where you are happy for people to do anything with your code. Use for .Net core, jQuery and Node.js - MIT License on Wikipedia

    license good 3
    Figure: Good Example – Apache License - for projects where you require attribution. Microsoft use the Apache license for MVC, EntityFramework, SignalR and Roslyn - Apache License on Wikipedia - Used for all SSW Open Source Projects.

  9. Do you have a clean git history?

    Maintaining a clean git history is important for readability and understanding the changes that have been made to a codebase. This is especially important when working in a team, as it allows you to see the changes that have been made to a file over time, and who made them. This can be useful for debugging, and for understanding why a particular change was made.

    Things that create a good git history include:

    • Granularity of commits
    • Descriptive commit messages
    • Easy to maintain (i.e. easily revert an entire feature)
    • Never lose history

    Squashing Pull Requests

    Video: Git MERGE vs REBASE: Everything You Need to Know (4 min)

    Squashing commits is the process of combining multiple commits into a single commit. This allows for the repository history to reflect changes to the application over time, rather than individual commits making up a feature which can be hard to follow as they give little context to the feature that the commit is being added for.

    Good Pull Request titles

    When creating a pull request, it's important to have a clear and descriptive title. This is important when looking back at the git history, as it allows you to see at a glance what changes were made in a particular pull request.

    Preserving file history

    Often developers will move files around and have major changes to the contents leading to the file history being lost as the the operation will be seen as a delete and add file because of the differences in contents.

    This can be avoided by using the git mv command to move files, or by breaking up the operation into smaller chunks i.e.: change content and then move the file as separate commits.
    📝 Git Tips - Making structural and content changes (4 min)

    Merging multiple repositories

    Sometimes you have a system that was designed in multiple repositories, and you want to merge them back together. This can be a complex process, but it's important that you know what to do when this situation comes up in order to not lose history.

    Source tip

    The process of a source tip is to stop using source code from 1 repository as of certain date, and start using it from another repository.

    This process leads to a situation where you have a couple of projects/folders of code all being added to a repository as a new commit, and developers would need to look in an alternate place to see the history of that portion of the codebase.

    Figure: Bad example

    Merge multiple repository histories into one

    It's important when combining git repositories that you bring all the history with you. This means that even if the files were added physically to a new repository today, developers will be able to see all the commits originally created in the original repository.

    Figure: Good example

    Writing descriptive commit messages

    It's important to have descriptive names for commits so that you can easily keep track of what was achieved after each commit was applied. Knowing what was achieved when the commits were made will make it easier to retroactively squash related commits as you'll know what work was done. In addition having descriptive commit messages makes it easier for a reviewer to see what you were trying to achieve in your pull request.

    Read more about writing descriptive commit messages.

    Conclusion

    Maintaining a clean git history is important for readability and understanding the changes that have been made to a codebase over the lifetime of the repository.

    Below is a summary of the things that create a good git history and the methods to achieve them:

    Granularity of commitsDescriptive commit messagesEasy to maintainNever lose history
    Squashing Pull Requests
    Good Pull Request titles
    Preserving file history
    Merging multiple repositories
We open source. Powered by GitHub