Alex's Adventures on the Infobahn - git

Comparing Forge-Based and Email-Based Workflow for Open Source Projects

2023-10-22T12:22:00+01:00

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)

Living la vida ELPA

2012-07-10T12:45:00+01:00

I've been running Emacs 24 direct from the version control tree (technically a git mirror, bzr still confuses me) for some time now. As many people have mentioned ELPA is one of the big features that helps de-clutter an Emacs users ~/.emacs.d directory. I thought it might be a useful exercise to discuss which packages I'm now loading from ELPA and which I still track directly.

First and formemost is my my dotemacs collection. Weighing in at around 2700 lines of elisp it's small by some standards. I've toyed with moving my config across to things like the Emacs Starter Kit but I'm not sure if it's worth the transition pain. There is certainly a lot of cruft in my code but there is also quite a lot of muscle memory now invested in it. I have been trying to modularise it a little more but to be honest most of that was driven by a desire to get autoload working nicely which is no longer much of an issue as my session tends to stay up for weeks at an end.

I'll gloss over edit-server.el surfice it to say I'd hope your not surprised I keep the development version running given it's for my extension ;-)

After that we have Johnathan Rockway's eproject. I work with lots of code bases during the day and some sort of sensible project type structure is a must. I've tried a number of different solutions and this one stuck as it was fairly lightweight and easy for my smaller lisp brain to extend. I've even managed to contribute some changes back. As a result I find tracking the bleeding edge of development useful.

The same reason applies to Stephen Bach's lusty-emacs. While ido-mode and ibuffer work well for speed nothing matches lusty's lazy file and buffer matching. It can get a little too much once you start dealing with hundreds of buffers at a time (something midnight-mode is trying to keep on top of). It's still seeing some activitiy on the repository hence the local checkout.

Finally the biggie but generally unused cedet. There has been some work to make it comparitively easy to run out of a src checkout and as long as it's included early enough it won't conflict with the built in cedet shipping with Emacs 23+. I still haven't really made much use of it although I have managed to get a completion out of it when editing some C. It's basically sitting there until I can commit enough time to figuring out how to use the beast.

Finally a quick review of the ELPA packages that I've got loaded. Obviously there is the latest org-mode which I'm spending an increasing amount of time in. I also have my favourite zenburn-theme for easy on the eyes goodness. The popular GIT interaction mode magit also sits there which I use every day. js2-mode and ssh_config_mode completes the list of modules that I actually use.

I have a number of additional things in there which I don't actually use at the moment but I plan to try out including nose (for python unit test), jsshell (for JavaScript coding) and another one I see a lot of the wizards using yasnippet but again is awaiting time to play with.

So what ELPA packages have you discovered and what hidden gems to you track directly in your .emacs.d?

Finally public

2010-01-25T12:41:00+00:00

After much faffing about with repeated sending of faxes to multiple numbers I finally proved I was human and accountable enough for "Edit with Emacs" to appear on the Chrome Extension Gallery. This almost immediately showed up some documentation and usage usability issues so I spent some of my spare time at the weekend creating an options page. I've also got a growing number of feature branches coming in from other github users so I merged some more contributions into the v1.4 release.

I have to say the usage of git as an SCM tool as well as github's non-fussy functional website makes managing contributions a lot easier. It's nice to see the world has moved on since the venerable SourceForge was the only option for those who didn't want to bother maintaining their own project infrastructure.

One of the feature branches being proposed is changing the interface to the "Edit Server" to pass a richer set of information about the text area being edited. This would allow the server to do clever things like position the frame near the position of the text area on the browser and possibly manipulate fonts. So far I'm trying to keep the current edit server calling conventions similar to those offered by other similar extensions that need to do a similar thing. Although for Emacs users edit-server.el will surely be the default and most used method it seems churlish to break compatibility for those that prefer to run/hack other servers. I've been documenting the URL conventions so it would be nice if I got some feedback how to maintain a useful extensible "API" for the broadest range of solutions.

Morning coffee for my workstation

2009-12-15T10:36:00+00:00

My work machine has always been slow in the mornings. I may have moaned about this before but it's mainly due to the rather excessive overnight processing it does (convert a 3.8G CVS repo into a 714M GIT repo). This tends to leave all the active applications somewhere in swap. With 3G of RAM in my machine this shouldn't really be a problem. Last night I enabled a very short script to run at 6.00 every morning:

#!/bin/bash
swapoff -a
sleep 10s
swapon -a

The machine certainly seemed a lot snappier this morning when I sat down in front of it.

Distributed VCS

2009-06-09T10:17:00+01:00

I've mentioned distributed version control systems a few times. It was interesting note the advice that Savannah is giving about recovering from a recent disk crash. Both Git andMercurial based projects can restore from local repositories as they contain all the revision history within them. The centralised version control systems are relying explicit backups being made. History has proved that getting backups done right is harder than it looks. If your running an open source project there is a lot to be said for having ever developer mirror you code for you. To slightly misquote Linus*: "Only wimps use backup: _real_ men just upload their important stuff and let the rest of the world mirror it".

* The original quote mentions tape and ftp which dates it a bit.