Forem: MousePaw Media

How to rename 'master' in an organization

Jason C. McDonald — Tue, 07 Jul 2020 03:48:47 +0000

We were deciding what to rename our primary development branch...

Goodbye Master, Hello...What?

Jason C. McDonald for MousePaw Media ・ Jun 29 '20

The result: devel won! It will join fresh and stable as our triad of protected branches.

Today, we started the transition from master to devel. While many guides exist to explain how to rename master on your own repositories, this gets a little more complicated in a team.

Here's a few things you can do to make that transition easier.

Phase 0: Prepare

Make sure your team knows what's happening. Give them a few weeks notice. Explain your motivation for renaming master.

Seriously consider giving them a say in what the new primary branch should be. Cultural and historic issues aside, master was never a particularly insightful name, so take the occasion to find one the majority of your team actually likes! You can see some of our thoughts on four candidate names for the primary branch on the article mentioned above.

Set a date for the start of the transition. It's best if you pick a period somewhere towards the start of a development cycle, whatever that means to you, to limit disruption to workflow. Don't let the word "disruption" scare you off; chances are, this will go smoothly, but you still don't want to risk a hiccup a few days before something is supposed to ship to prod. ;)

Phase 1: Renaming

This is where you actually rename the branches! For this guide, I'll use devel for the new name, since that's what we picked, but you can substitute whatever name you prefer in there.

Here's the command for this, taken from this article by Alexis Moody, and adapted to our use:

git branch -m master devel
git push -u origin devel

Next, on your repository management tool — GitHub, GitLab, Bitbucket, Phabricator (in our case), or whatever) — set the new devel branch as the primary.

Do not yet delete master!!! This helps protect against initial bumps in the road:

Developers can still pull from master.
The CI/CD pipeline won't all break right away.
It's extra insurance against data loss.

Instead, create a Git hook to block any changes pushed to master. This is a gentle way to transition your developers until they get into the new habit.

Now, go change your build pipeline. This part may or may not take a while.

Phase 2: Retraining

Instruct your developers to update their local copies, and give them time — say, a month? — to do it! Be sure to provide the commands to do so (see below).

That commit hook will prevent them from pushing to master out of habit, but the fact that master still exists (but not as the primary branch) will help smooth the transition.

To update a local copy to the new branch name, we're using the following code, based on this article by Scott Hanselman:

git checkout master
git branch -m master devel
git fetch
git branch --unset-upstream
git branch -u origin/devel
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/devel

At this point, you should also update your workflow documentation. If one or more of your team members has some extra bandwidth, consider asking them to undertake this. It will help them get into the habit of thinking of "devel" instead of "master".

During this time, builds should still be running, but on the new branch name (barring errors). Most issues with the changes to the CI/CD will resolve during this time.

Phase 3: Deleting `master`

After about a month, your team will likely have updated their workflows and habits, at least for the most part. You can now delete master on each of your repositories:

git push origin --delete master

Each of your developers can see the change by running the following on their local copies:

git fetch -p

Expect a few fresh issues with your CI/CD (there's always one typo, isn't there?), but most of those should be easy to iron out.

And, you're done! You have a shiny new primary branch with a useful name. What's further, you'll never have to do this again.

...or so we hope!

Okay, at least that's how it's supposed to go. We're through Phase 1 without any hiccups, but we'll be sure to update this post if there's anything else that comes up in the next month.

For us, master is set to be deleted on all our repositories on Monday, 03 August 2020! If there's any dramatic explosions of the build pipeline, we'll share the details on Twitter. :)

Is there anything you or your team has done to make this transition go smoother? Let us know in the comments!

^{WARNING: This is not the place to debate about whether master should be renamed. Any comments to that effect will be hidden and reported.}

Goodbye Master, Hello...What?

Jason C. McDonald — Mon, 29 Jun 2020 23:46:20 +0000

Next week, we'll begin the process of renaming the master branch on all our repositories to something else.

In case this movement in tech is a bit unfamiliar to you, or you want to know how to do this yourself, @afrodevgirl has an awesome and succinct summary:

Replacing master with main in Github

Alexis Moody ・ Jun 16 '20

#git #github #inclusion

Why the Delay?

We've had this on our plan since mid-June, but we were in the middle of GAME MODE 2020, and given the pace and task prioritization involved, attempting this change then would have been more than a little disruptive to workflow, and quite prone to error.

Now that we're moving into July and back into our usual tasks, the time is right to make the transition.

Renaming the master branch is easy enough itself, but that really belies what's involved:

We have to rename the primary branch on over two dozen repositories.
We have to change the entire CI/CD pipeline to react to changes on the new primary branch name.
We have to update all our standards, policy documents, and workflow documentations to reflect the new primary branch name.
We have to test all of the above.

That really isn't too much to do, but it can easily turn into several days of poking the build system and pipeline with a stick. We don't mind, but hopefully you can see why we had to wait until now!

Picking a Name

We've had a couple of discussions recently as a team about what to call this new branch. After all, if we're changing it anyway, we should take the occasion to find a good name!

Right now, our protected branches look like this:

master: the current development version.
fresh: the current beta or pre-release version.
stable: the current release version.

Honestly, master never made much sense. We only used it because that was the norm for Git.

We've narrowed the possibilities down to four candidates:

`devel`

Since the primary branch contains the latest development version, which changes constantly, the name devel might make sense. It sends a clear message to users browsing the repository that this version isn't intended for production use.

devel, fresh, stable. That seems to spell out our workflow pretty well.

`edge`

Ben Halpern mentioned this name in a comment thread, and I (Jason) rather liked it. It refers to "bleeding edge", which implies that you could use this version of the code, but that you'd need to beware sharp edges and bugs.

edge, fresh, and stable sounds pretty cool, doesn't it?

One downside: this may now also be reminiscent of a certain web browser, which could muddy the issue.

`main`

This is an option only because GitHub uses it by default. Developers are likely to get used to it, if they aren't already.

The problem is, main seems to have the same vagueness of purpose master did, if not moreso. What would you find in main? The main version? Sounds good to Mr. End User...but they'd be wrong.

Personally, with main, fresh, stable, it makes stable read as stale to me. But maybe that's just my dyslexia talking.

`trunk`

An oldie but a goodie. This term comes from Subversion, the industry standard version control software before Git really took off. We also get "branch" from this.

Every branch is based on trunk. It just makes sense! But does it fit our workflow? trunk, fresh, stable. Not sure.

What Do You Think?

We're running a poll on our Phabricator instance for all of our contributors to weigh in. You're encouraged to register for an account there via your GitHub (we usually approve new accounts within a couple of hours) and put your two-cents in.

Alternatively, leave a comment here.

Ultimately, the team will make the final call at week's end, so we can start the transition on Monday, 06 July, but we'd love your feedback!

^{This is not the place to debate about whether master should be renamed. Any comments to that effect will be hidden and reported.}

Development Log: One Month In

Jason C. McDonald — Mon, 29 Jun 2020 23:16:47 +0000

Happy almost-July!

We've reached the end of GAME MODE 2020, and while we've made significant progress, DiamondQuest is far from finished. What now?

Revisiting Expectations

DiamondQuest's development was slowed out of the gate by some unexpected changes to our team, difficulties nailing down the main structure of the game, among other delays.

Yet, even before June, we knew it was a very real possibility that DiamondQuest wouldn't be ready by July 1st! That's just the nature of software development.

But that's okay. Even though the official GAME MODE 2020 is over, we're continuing development on DiamondQuest, and will continue to update this development log accordingly. Our regular game engine development work is calling to us, but we'll keep devoting some of our time to DiamondQuest until it's done.

Besides, we're rather proud of what we accomplished in June, regardless!

Map Generation

With the help of open source contributor Harley Davis, Jason C. McDonald was able to finish the map generator:

^{DiamondQuest block textures by WightKing for MousePaw Media. Licensed under Creative Commons Attribution-NonCommercial-ShareAlike-NoDerivatives 4.0}

The deeper you go, the lower the probability of encountering caves and dirt, but the higher the probability of encountering treasure. This is generated by the final code (more or less), so improving the map generator is as simple as tweaking a couple of constants later.

Player Movement

Elizabeth Larson, Jason, and Harley built the model that the player avatar, The Miner, will use to be "aware of her surroundings", and to specify whether any particular player action is possible or not.

That player movement is largely functional in the model, although it doesn't yet render on the screen. Elizabeth is expanding the sprite sheet for The Miner so we have all the artwork we need for that avatar.

Math Puzzles

Adeel Hussain and Graham Mix have been building the model for generating the math puzzles the player has to solve, and getting the pieces in place to render that puzzle on the screen.

Treasures!

Open source contributor Anna Dunster has been creating some amazing artwork for the treasures you can find in DiamondQuest!

^{Ammonite fossil}

^{Vescular Basalt}

^{I hope it's not overdue...}

^{Oh, there's my other sock!}

^{DiamondQuest treasure art by Anna Dunster for MousePaw Media. Licensed under Creative Commons Attribution-NonCommercial-ShareAlike-NoDerivatives 4.0}

Want To Help?

We'd love to have your help! Whether you're a coder, an artist, a sound designer, or a musician, your contributions would be greatly appreciated.

Visit our website to learn more and join in the fun: https://mousepawmedia.com/developers/contributing

Development Log: All About Structure

Jason C. McDonald — Fri, 12 Jun 2020 20:16:14 +0000

We're halfway through GAME MODE 2020 — I know, time flies, right? — and the project is starting to take shape. But if you were to try and run the game right now, you might wonder what we've spent the last two weeks doing.

After naming things, structure is probably the hardest part of application development.

Goal: Just Render Something!

It's hard to build a game when you have no way to see the results. That's why one of the first goals in game design is just to get something rendering in the appropriate context, which in our case would be a window.

Rendering an image in a window using Pygame? How hard could that be? While it's true there are dozens of tutorials describing exactly that, it won't do the development team much good if the code used for rendering something to the screen is throwaway code with no reuse value.

This is where program structure comes into play. Who manages the window and its surfaces? How are those surfaces accessed for updating? How does the game even known when to redraw anything?

Harley, one of our open source contributors, suggested using a Model-View-Controller structure pretty early on. It definitely fits the problem we're trying to solve, but picking a technique is the easy part. Now we had to answer a hundred questions that only became apparent as we started building:

Redrawing the window is expensive! How does the MapView know when the MapModel has been updated?
How will we keep track of the player position?
Rendering a math puzzle to the screen is harder than rendering the grid-like game map; how do we know when to redraw parts of that?
Does everything depend on Window, or does Window actually manage things?
What part of the code decides when to update Views?
What part of the code decides (roughly) where on the screen one thing is in relation to another?

The list goes on, and none of those questions had easy answers. We couldn't even work out most of the solutions until we started just building something.

The Joys of Live Coding

The MousePaw Media team makes extensive use of Visual Studio Code Live Share. Prior to GAME MODE 2020, we were doing plenty of pair programming, but once we started work on this game, we found more ways to use it.

One approach we found helpful initially was mob programming, where a whole bunch of us joined a Live Share session at once and started chatting about how to structure the project. Since we each have our own sector to work on, we started mocking out some beginning class structures and determining module dependency order.

We didn't produce working code in those first two sessions, but we produced something, and we had a vague idea about what went where.

We've also been employing live coding. I especially will post a read-only Live Share link to the project chatroom when I'm working, so that anyone can pop in and watch. That provides opportunities for learning on both sides; they pick up some of my Python technique, and I sometimes get valuable feedback as I work. However, as it doesn't require the same level of attention as pair programming, observers can work on their own thing even while watching me.

What About Issue Tracking, Anyway?

Our goal to get an early version of the game built by the end of the month, paired with the delays from hashing out the structure, has meant that issue tracking has rather fallen by the wayside.

We are not without direction, mind you! Our initial planning work on the wiki provides a pretty solid roadmap. However, when you can't really pin down how the program is even structured, issue tracking becomes difficult.

Despite being a strong proponent of issue tracking, I've been okay letting this slide for a while. Ultimately, the primary goal is to ship working software, and every part of the process should facilitate that goal. Issue tracking and code review are almost always essential, but we've found it reasonable to let both go temporarily so we can focus all our attention on getting something building.

Yes, you read that right...we temporarily ditched code reviews! Because we've been building the very structure that everyone's work relies on, I didn't want to hold up four other people while waiting for one person's work to get approved. We're moving so fast at this point, corrections to the code occur faster than the reviews themselves! It's easier just to allow somewhat broken code onto the master branch and get it in a subsequent commit. We only started employing this at all in the middle of this week, and the reviews are mostly "in the next commit, address this" sort of comments. Precious little is being held back.

Code reviews and issue tracking aren't out of the picture forever. Once the main structure is stable, we can reinstate both in full if we're certain they'll complement our efforts rather than hinder them.

Why yes, we are making progress!

Last night, we hit a milestone. Just before 9 PM, I finally got the MapModel, MapView, and Window classes communicating in just the right way to allow Harley's main game loop to trigger a screen update.

The result?

Those are individual blocks, loaded from Wightking's blockset image, cropped, scaled up, and rendered on the screen according to the map generated by the code.

I had to temporarily hard-code how many columns were showing on the screen, and what the map depth was right now, but I expect to get those parts sorted before the weekend is out. But the rest is production code, which we can continue to revise until everything works the way we want.

Although I had the honor of being the first person to get the map drawing on the screen, this victory really belongs to the whole team! Everyone has played a role in getting DiamondQuest this far.

It may not look like much, but this is huge. Our structure is just about done.

^{Block images are part of the DiamondQuest Tileset by Wightking for MousePaw Media. Licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0}

Meet the Miner!

I can't end this development log without acknowledging the amazing artistic work of Elizabeth Larson, who has been creating the sprites for The Miner:

These will be processed to look like the 16-bit character you'd expect from our game. Honestly, I think The Miner is delightful!

^{DiamondQuest character art by Elizabeth Larson for MousePaw Media. Licensed under Creative Commons Attribution-NonCommercial-ShareAlike-NoDerivatives 4.0}

Join In!

See something you like? We'd love to have your help!

If you're a programmer, consider where you'd like to help: Map Generation, Player Movement, Math Screen, or Miner's Log. Of course, if you can't decide, you can always poke around until you find something interesting.
If you're a graphics designer, we need treasures! These would be larger, 16-bit style graphics of all sorts of goodies: ancient pots, dinosaur bones, coat hangers (yes really), rubies, gold nuggets, and of course, diamonds. The more treasures that can be found in the game, the more fun it'll be!
If you're a musician, we've love contributions to the OST. In a later post, I'll be sharing a sample of the original menu music I've composed for the game.
If you have any other skills that might be useful, and want to join in, we want you too! There are always lots of tasks that need doing, even beyond the obvious coding, drawing, and recording. Come on in!

Visit our website to learn more and join in the fun: mousepawmedia.com/developers/contributing

Development Log: Planning a Game

Jason C. McDonald — Tue, 26 May 2020 05:10:00 +0000

GAME MODE 2020 starts next week, and we're eagerly preparing for it.

Task Planning

One of the chief challenges in building a game in a month is determining how everyone can work together. There's this pesky little thing called Brook's Law that we're up against:

Adding more people to a late project makes it later.

Many of the same dynamics that make this true can also slow down a project because of the size of the original team. To avoid this problem, we have to be very deliberate about how we assign tasks.

We've been planning DiamondQuest over the last couple of weeks, so we can dive right into coding on June 1st. As per our usual workflow, we've been mapping out all the design goals and features on our wiki.

During our planning meeting on Saturday, we decided to divide up features into four sectors, with two of our eight developers assigned to each sector. In talking through the features, we identified four areas:

Map generation
- Generating the map, including distributing treasure blocks,
- Rendering map textures,
- Loot tables, and
- Providing map information to other parts of the code.
Player movement
- Player controls,
- Rendering avatar sprite,
- Avatar movement & map interaction.
Math screen
- Generating math problems,
- Interface for solving math problems.
Miner's Log
- Tracking treasures found,
- Player profile and score,
- Game menu.

By dividing the game tasks in this way, each component can be built in relative independence to the others, speeding up development time. We don't have to worry about developers stepping on each others' toes, and Brook's Law is averted.

Development Workflow

Another component we needed to address was the turnaround time for code reviews. When you're trying to build a game in a month, you don't have time to review, test, and polish large changesets. Instead, we plan to make small, frequent commits.

That is, instead of building a huge thing, like the loot table, in one shot, we build a small thing that's part of it, like a "dice roll". That gets reviewed and landed in a matter of hours, and the next piece can be built on top of it. We hope that by working in this manner, the project can support the contributions of many people without slowing down.

Game Graphics

My good buddy Wightking created the tileset for DiamondQuest. Since we're going for a 16-bit inspired platform-style game centered around mining and archaeology, we have to have cool things for the player to find.

In order to keep things simple, we have three types of treasure block that are randomly scattered amidst the stone blocks that make up most of the map. These are the Fossil Block, which yields some sort of fossil or bone, the Artifact Block, which yields some archaeological artifact or other man-made object, and a Mineral Block, which yields various gemstones and precious metals.

These are just part of the lovely tileset that Wightking built for the game. You'll see more in later updates!

Elizabeth Larson has also been working on the concept art for the miner character:

^{Tileset images are part of the DiamondQuest Tileset by Wightking for MousePaw Media. Licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0}

^{DiamondQuest character concept art by Elizabeth Larson for MousePaw Media. Licensed under Creative Commons Attribution-NonCommercial-ShareAlike-NoDerivatives 4.0}

Join In!

See something you like? We'd love to have your help!

If you're a programmer, consider where you'd like to help: Map Generation, Player Movement, Math Screen, or Miner's Log. Of course, if you can't decide, you can always poke around until you find something interesting.
If you're a graphics designer, we need treasures! These would be larger, 16-bit style graphics of all sorts of goodies: ancient pots, dinosaur bones, coat hangers (yes really), rubies, gold nuggets, and of course, diamonds. The more treasures that can be found in the game, the more fun it'll be!
If you're a musician, we've love contributions to the OST. In a later post, I'll be sharing a sample of the original menu music I've composed for the game.
If you have any other skills that might be useful, and want to join in, we want you too! There are always lots of tasks that need doing, even beyond the obvious coding, drawing, and recording. Come on in!

Visit our website to learn more and join in the fun: mousepawmedia.com/developers/contributing

GAME MODE 2020: Building a Game in One Month

Jason C. McDonald — Thu, 30 Apr 2020 23:38:47 +0000

Announcing GAME MODE 2020, from June 1st through the 28th, where we're going to attempt to build an open source game in one month. Our entire development staff is putting their usual work on hold for the month of June to work on a brand-new game: DiamondQuest!

The Game

DiamondQuest is a mining-inspired, 16-bit-style platformer where you search for buried treasure, fossils, and gemstones, using your math skills to dig. The game will use positive reinforcement to encourage players to keep playing and to challenge themselves; the relaxing, non-threatening game environment provides a new twist on math drills, without triggering math anxiety.

Perhaps most exciting is that this will be an accessibility-first game, designed to accommodate motor-impaired players who normally cannot play computer games. The keyboard-driven gameplay is designed for players who are either limited to single keyboard presses (e.g. with a head pointer) or have slower reflexes. The concept for DiamondQuest came from Lead Developer Jason C. McDonald's long-time desire to build a game for a friend from college who lived with cerebral palsy.

Tech Specs

Python 3.7
Pygame (probably)
Packaging: pip, PyInstaller, Snapcraft, (+whatever else!)
Target: Win/Mac/Linux Desktop
VCS: Git
Development Platform: Phabricator (MousePaw Media DevNet)
Project License
- Code: BSD-3-Clause
- Graphics/Music: Creative Commons BY-NC-SA (some CC BY-NC-ND)

The game will be completely free (as in free coffee). We won't be making any money from it whatsoever.

Call for Contributors

To pull this off, we need all the help we can get! We're putting out the call for contributors: developers, graphics designers, musicians, packaging gurus, math nerds (to help with the educational component), game design enthusiasts, and the like. Whether you're a novice or an expert, you'll find something to do.

NOTE: We especially need artists; we have one on our team, but having more will be a deciding factor in whether we accomplish our goal!

We'll be collaborating using Phabricator and Git, on MousePaw Media's DevNet platform. We have a robust issue tracker, code review system, automatic CI/CD pipeline, and chatroom. Instructions for getting started can be found at mousepawmedia.com/developers

As we move closer to the start of GAME MODE 2020, we'll be announcing related events, including live collaboration sessions. We'll also be publishing Development Updates here on DEV, so follow us for the latest!

So, can we do it? We're going to find out, and we would love for you to join us!

Forem: MousePaw Media

How to rename 'master' in an organization

Goodbye Master, Hello...What?

Jason C. McDonald for MousePaw Media ・ Jun 29 '20

Phase 0: Prepare

Phase 1: Renaming

Phase 2: Retraining

Phase 3: Deleting master

...or so we hope!

Goodbye Master, Hello...What?

Replacing master with main in Github

Alexis Moody ・ Jun 16 '20

Why the Delay?

Picking a Name

devel

edge

main

trunk

What Do You Think?

Development Log: One Month In

Revisiting Expectations

Map Generation

Player Movement

Menu

Math Puzzles

Treasures!

Want To Help?

Development Log: All About Structure

Goal: Just Render Something!

The Joys of Live Coding

What About Issue Tracking, Anyway?

Why yes, we are making progress!

Meet the Miner!

Join In!

Development Log: Planning a Game

Task Planning

Development Workflow

Game Graphics

Join In!

GAME MODE 2020: Building a Game in One Month

The Game

Tech Specs

Call for Contributors

Phase 3: Deleting `master`

`devel`

`edge`

`main`

`trunk`