In the open source technology universe, how teams coordinate, collaborate and contribute is determined by the workflow they opt for. At a high level, workflows can fall into one of two camps: Forge-based or Email-based workflows. Forge-based workflows gained popularity with platforms such as GitHub and GitLab, while Email-based workflows have been a stalwart mechanism for open source software development with mailing list platforms like GNU Mailman and SourceHut.

In this post, we will look at the benefits and drawbacks of the various approaches, hopefully lending insight to what will work best for your project.

Forge-Based Workflow

Forge-based workflows have revolutionised open source software development. Various advantages have made it an accessible choice for many, including:

1. User-Friendly

Forge-based platforms such as GitHub or GitLab feature a friendly GUI and offer excellent documentation, making it super easy for beginners to contribute to open source projects without needing an in-depth understanding of git and email tools.

2. Centralised and Organised

These platforms provide central repositories that make project management streamlined. Access controls, issue tracking, continuous integration, and other tools all exist in one place.

3. Collaborative Environment

The pull-request model common to forge platforms encourages collaborative code review, making it an excellent tool for open-source projects where code quality is a priority.

However, there's a flip side to this coin:

Cons: Risk of Vendor Lock-in

Choosing a specific forge platform means accepting their choices of features, tools, standard practices, and policies which subtly enforce vendor lock-in. For most open source projects this also means relying on the forge supporting projects with cost free access to features and CI time.

Email-Based Workflow

Despite being considered 'old school', email-based workflows still have merit in today's software development world. They offer:

1. Decentralized and Flexible

In sharp contrast to forge-based workflows, email workflows are inherently decentralized. This approach offers more flexibility for contributors and maintainers alike, as they are not bound to tools offered by a single platform.

2. Line-by-Line Review and Inline Feedback

Email-based workflows stand out when it comes to the review process. The nature of emails allows for contributors and reviewers to break down commits line-by-line. This allows for more granular attention to detail, leading to clearer communication about specific code changes. Additionally, the threading mechanism of emails allows for inline commentary during reviews, making it easier for contributors to respond and iterate on feedback. This approach can encourage deeper understanding and discussion around code changes, leading to well-reviewed and robust code contributions.

3. Enhances git Understanding

Contributors working with email-based workflows generally have a better understanding of git because it requires more hands-on actions when sharing code.

However, they too have potential drawbacks.

Cons: Less Beginner-Friendly

Email-based workflows requires a steeper learning curve and are less friendly for collaborative code reviewing, making it challenging for new contributors to a project.

Adapting Open Source Projects: Email to Forge Workflow Transitions

Transitioning from an email-based workflow to a forge-based one should be a meticulously planned process that respects the existing community's culture and comfort. It's pivotal to keep this move as an evolution rather than an abrupt change.

Initial steps in such transitions can include moving non-code elements to the forge platform. Functions such as issue tracking, documentation, and discussions could be the first set of activities transferred to the forge platform. This strategy allows the contributors to become proficient with the platform’s tools and interfaces while keeping the code contributions intact on email lists.

Your project might encompass several sub-systems, and it could be worth considering this while transitioning. Instead of transforming the entire project at once, one could start by moving individual sub-systems to the new workflow. This incremental, phased approach can prevent chaos and reduce the chances of any significant disruption in the project's flow.

Following the sub-system shifts, the project should then introduce acceptance of pull requests or merge requests created by maintainers. These PRs should still contain code that underwent email list reviews in the previous workflow, ensuring the robustness of code quality.

The final stage of the transition is welcoming all contributors to submit merge requests through the forge platform. The key is to ensure that contributors understand the reasons behind the shift towards a complete merge request approach. They should be given clear guidelines about how and why to use merge requests, making them comfortable with the transition, and empowering them to take full advantage of the tool's capabilities.

In transition, it's necessary to alleviate concerns, clarify intents, and provide resources to learn and help the contributors adjust to the new workflow. Both email and forge-based workflows hold their place and value in open-source. So, when transiting, the project needs and the contributor adaptability should be the cornerstone of your strategy. No two projects are the same, and neither are their paths in adopting new workflow models.

(Fuller disclosure: as @epilys noticed this post was generated via chatgpt. I may have spent more time fiddling with my pelican settings to make sure the author slug was properly shown than I did iterating with GPT4 on the article. It has had some light copy-editing since to clean up some copy and paste errors between iterations and some of the more artificial phrasing it used)