Rules to Better Open Source Software - 11 Rules

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

• Different licenses have different requirements. See what to check before installing 3rd party libraries for more info.

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:

• RedHat
• Microsoft
• Google
• Netflix
• AirBnB

🧱 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:

• jsakamoto/Toolbelt.Blazor.HotKeys - This repo contains a small library that allows you to add hotkeys to your Blazor apps

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.

This issue is described beautifully here Open Source Contribution Etiquette by Miguel de Icaza.

For the original article check out Don't "Push" Your Pull Requests by 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 PR 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

Poor early communication can lead to mis-directed work and pull requests not being accepted.

• Developer has good idea for project
• Bashes away and writes 600 lines of code
• Submits pull request
• Core contributor looks at large pull request They don't fully understand purpose of request / the problem it solves They don't like that the PR author hasn't followed the existing coding standards They make a push back comment

✅ Good communication contribution

Good communication leads to collaboration and better outcomes for the author and the project.

• 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

Projects with internal teams

• Internal 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

It is important that users of your open source contributions are aware if you are maintaining them and keeping them up to date.

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.

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

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.

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.

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 commits	Descriptive commit messages	Easy to maintain	Never lose history
Squashing Pull Requests	✅	✅	✅
Good Pull Request titles		✅	✅
Preserving file history			✅	✅
Merging multiple repositories			✅	✅

Some companies want to keep their projects closed-source in order to profit from their products. However, there are several benefits to keeping the source open including:

• Community contribution and feedback
• Allowing controlled free use of your products

We want our projects to be financially sustainable while supporting the open-source space. Let's take a look at the licensing options for open-source projects on GitHub.

Option 1 - No License

As per GitHub's documentation, no author is obligated to choose a license for their project. Without a license, the default copyright laws will apply.

Pros

• No Effort: No effort required on the author's part.
• Some control: Retains some control of the source-code.

Cons

• Not Permissive: Generally, users will have no permission from the author to use, modify or share the software. However, GitHub allows users to Fork and view code as a part of their terms.

Option 2 - MIT

The MIT License is a well known license trusted by many open-source projects.

Examples include:

• Dotnet
• Ruby on Rails

Pros

• Permissive: Allows for commercial and private use as well as distribution and modification of the author's software.
• Collaboration + Community: Promotes an open and collaborative environment with community feedback.
• Short and simple: The text of the license is simple and quick to understand.

Cons

• Limited Patent Protection: The MIT License doesn't include explicit patent grants or protections.
• Lack of clarity on Trademarks: The license doesn't address the use of Trademarks associated with the software

Option 3 - Copyleft (e.g. GPL)

A copyleft license like the Gnu Public License promote and protect the principals of open-source software. Though they may also introduce complexities and potential limitations that users may be deterred by.

Examples include:

• Ansible
• Bash

Pros

• Collaboration + Community: Promotes an open and collaborative environment with community feedback.
• Protection Against Exploitation: Guards against consumers taking the source code and making proprietary modifications in a closed environment.

Cons

• Complexity: Some developers and organizations may find a copyleft license to be too complex and stringent.
• Perceived Risk: Copyleft licenses may discourage contributors or participators through perceived risk.

Option 4 - Proprietary

Companies often use a proprietary license when they prefer to have fine-grained control over their intellectual property.

Examples include:

• Mozilla
• Duende

Pros

• Better control: Authors have fine-grained control over their source code and how it's used.
• Benefits of community development: Authors can still benefit from the community engaging with their source code

Cons

• Cost: Drafting and iterating upon your license will cost time and money.
• Bad actors: Authors will need to be vigilant of bad actors abusing the license and choose to pursue them.

Option 5 - Functional Source License (FSL)

Sentry introduced the FSL as a way to support the open-source community whilst retaining control over their IP.

Examples of projects with this license include:

• Sentry
• GitButler

Pros

• Protection: Retains control over source code for up to 2 years
• Free and Open-Source Software (FOSS) Values: Automatically converts to MIT/Apache 2.0 licensing after 2 years
• Continual Iteration: Pushes the author to continually iterate on their project or risk third-parties competing with a forked version of the project.

Cons

• Not strictly Open-Source: While Sentry values FOSS, this license does not meet the strict definition of open-source.

Social Media is important for companies, and the employees. One of the things you can post is the improvements your products e.g. New features, bug fixes, upgrades etc.

Businesses should get their developers to do this, and then re-post it.

Your followers may not know about the changes and the ones who are grateful are likely to retweet or like your post. This also helps build a community around your product.

Benefits

For the business:

• Keeps your social media active
• Shows transparency (especially important for open-source projects)
• Shows you are actively improving your products
• Gets eyes on your product

For the developer:

• Keeps your social media active
• Visibility - Shows you are a useful employee This is helpful for your current role and future roles
• Shows you take ownership and pride in your work

The important things to include are

• What changed
• The problem it solves/value it adds
• Tag/link the product
• Link to the PBI e.g. GitHub Issue
• Done Video or screenshots

Make sure to post it on a few channels to reach a wider audience.
E.g. Make an announcement GitHub Discussion then link to it from a tweet, LinkedIn post, etc.

Example

I upgraded Tinasaurus (@tinacms + @docusaurus ) to Docusaurus v3 🚀https://t.co/fG6RAbnbsw

— Brady Stroud (@bradystroud_) May 31, 2024