The following post outlines important steps to consider when contributing the the Dev Launchers platform, with a specific emphasis on our monorepo located at https://github.com/dev-launchers/dev-launchers-platform. If you’re a dev working on one of our teams this is an especially important read!
TLDR: Don’t create PRs directly to master (unless you’re a Technical Lead creating a release.) Always keep your local branches up-to-date with your team’s “development” branch. All “features” worked on within a sprint should branch off from your team’s development branch, and PRs should be submitted back to said branch. And for Technical Leads: rebase your development branches often!
Our Model For Branching and Feature Flow
If you’ve heard of Git Flow or GitHub Flow, you’ll be familiar with many of the following concepts. BUT, you’ll notice some extra… stuff. I’ll attempt to explain all of this later in the post, but our model diverges from the aforementioned models for two main reasons. First, all of our different teams/products exist within a monorepo. Second, Dev Launchers is comprised of 100% volunteer devs and leaders who may not have the experience or time to fix broken things around the clock.
You’ll want to be familiar with the basic concepts of git such as pushing, pulling, branching, committing, and creating pull requests. I’ll also be referencing Agile in loose ways.
Before I dive into the specifics, I’ll describe four important phases a piece of code goes through as it’s making its way from infancy all the way to the working world within our system.
Can you believe I made this picture all by myself?
Stage One: Your local machine (or the feature branch) – Every sprint, these branches are created from the team’s “development” branch. One per new feature. This gives devs a place to explore, experiment, and break things as they’re pursuing implementing a specific feature or squashing a specific bug. Once a feature is ready it flows into…
Stage Two: The team/sprint branch (or the development branch) – EACH individual team within Dev Launchers owns their own development branch, which is treated as a central location containing the work of their current sprint. All feature branches for any given team should stem from their team’s development branch, and all feature branches should flow back into the same development branch. During a sprint, Technical leads are urged to merge/rebase from master often to squash any potential conflicts early! This branch is primarily maintained by the Technical Lead for the team, who handles integration as a sprint concludes in the next step…
Stage Three: Staging (or the master branch) – When a sprint is concluded, all of the work from the team’s sprint is merged into the master branch where it meets and mingles with fresh new code from all of our other teams. Our CI magic builds the app and deploys directly to https://staging.devlaunchers.org when any and all changes are detected in the master branch, allowing a final QA pass to be run to cover any large integration issues. Once we see everything is all clear, then…
Stage Four: Production (or the release branch) – We merge to our release branch, which automatically deploys the newest changes to the platform at https://devlaunchers.org!
Naming Conventions
This wouldn’t be a thorough guide for devs without a supremely dull section on naming conventions. Don’t worry, I’ll try to be quick. When creating branches within our monorepo there are two major rules based on who “owns” a branch.
- Feature Branches: These are branches owned by a single individual. If you create a branch, put your github username right in the front of it. Every time. Then, add a slash and describe what the branch is for in a few words. Let’s say I’m adding a feature to create a little virtual helper that walks new members through the signup process. I’d branch off of my team branch and create
pyxld-kris/create-virtual-helper-557(bonus points if you include the issue number you’re working on!) This is great for a few reasons. One, it makes it really easy to find your own branches when sorting through an alphabetical list. Two, it makes it really easy to NOT find a thousand other branches on accident! - Development Branches: This one’s even simpler and there are fewer of them to worry about keeping track of. All development branches follow the convention
development/team-name. Not much else to say on that one so here’s a zebra. 🦓
Allow Me To Explain
Some of you might be thinking that this adds an extra layer of annoyance, but please hear me out. I’ll take some time to justify this practice within the context of our organization, along with introducing some important concepts and related methodologies for handling branching.
First, if you’re a proponent of true CI/CD practices then I apologize for the incredible offense I have committed to you throughout this entire article. For my finishing blow I’ll hit you with this: our sprints are a whole month long… but in our defense, this is what we’ve found works best for us. That being said, if you have ideas on how we can improve this process we always want to know! For any curious readers who don’t know what I’m talking about, or think I’m just talking to thin air, here are a few things to search up: continuous integration, continuous delivery, continuous deployment, git flow, and github flow.
Now, onto why these rules are important for the current state of our organization.
- Everything is in one place
- There will always be things that break
- Everyone is a volunteer (but not volunteer firefighters!)
As we get more established on our QA journey, and perhaps re-engineer pieces of our deployment pipeline, I believe we’ll be able to move more quickly with less fear of breaking really important things. For now, though, it’s important that contributors have as many extra buffers and barriers to keep them from dislodging something that’s propping up a major section of the platform. When that happens, one of our Technical Leads has to take time to step in and correct the issue, or even worse… multiple tech leads have to bounce things back and forth until the issue is resolved. That’s time that those leads aren’t spending supporting their devs or working with product oriented members to create value on the platform.
Additionally, because of how our monorepo and release pipelines are structured, anything broken anywhere beyond a team’s development branch completely locks other teams out of making releases. If one team introduces a bug that isn’t quickly addressed in staging, any team merging there is blocked from pushing to production until the issue is resolved. Imagine having a month full of new features ready to release to users, having your team excited about an important milestone you accomplished together, but not being able to seal the deal! This problem, coupled with the volunteer nature of our organization, can create some pretty extended periods of blocking and frustration if strict guidelines aren’t followed.
Wrapping Up
The ending felt too abrupt, and instead of actually addressing the issue I added this section. Here’s a horse. 🐎🧡
Dev Launchers is a registered 501(c)(3) nonprofit organization and we need your donations to continue operating. If you’re able to, please consider making a tax-deductible donation!