(Re)naming things is hard
MP 133: Naming things is hard, but renaming things can be even harder.
I've been steadily working through the remaining issues that should be closed before the 1.0 release of django-simple-deploy. One of the last things to address involves reconsidering a name that's used throughout the project.
Renaming a variable that's used in a few places within a project doesn't take much work. However, renaming something that's used throughout a project, visible both internally and externally, can involve a significant amount of work. In this case, I decided to go ahead with the name change, and all the work that entails. I learned a fair bit about the impact of names in a growing project.
Names in django-simple-deploy
Django projects are built from apps, and the original name I used for the app was simple_deploy
. This ended up being confusing, because there were three names that were used: the project name django-simple-deploy
, the app name simple_deploy
, and the command name deploy
. To make things even more complicated, I found myself using the name simple_deploy as a nickname for talking about the overall project.
The name of the project, django-simple-deploy
, made sense at the time I started the proof-of-concept work. I still like that name today. The project aims to make Django deployments simpler, but it doesn't aim to help deploy all Django projects. It's quite a bit more descriptive and intentional than something shorter like django-deploy
.
The project is basically a single Django app, and every app needs a name. When I started this project, there wasn't a clear consensus on what pattern app names should follow. One pattern was to drop the django-
from the project name, and replace hyphens with underscores. The official tutorial at the time recommended this approach. So, I named the app simple_deploy
. This name was used in the codebase, and became a nickname for the project.
The tutorial for packaging Django projects has since been updated with much clearer recommendations:

If I want to follow the current recommendation, I need to change the app name from simple_deploy
to django_simple_deploy
.
Is it worth changing?
I decided the name change was worthwhile for several reasons:
- It's more consistent with current usage in Django, and I expect this project to be active for years to come.
- It's less confusing for everyone. There's no need to learn multiple names, and where they're used. (It's hard enough for people to learn when to use hyphenated names, when to use names with underscores, and why each is needed.)
- This change has significant public-facing impacts on how the project is used. It affects end users, authors and content creators (one of the primary user groups), and plugin developers.
It's a change that really needs to be made now or never, because it involves backwards-incompatible breaking changes.
Why is renaming hard?
Changing a name is just a matter of using your editor's Find & Replace feature, right? For a change that permeates your entire project, it's not quite that simple.
Changing the app name from simple_deploy
to django_simple_deploy
involved the following:
- Changing the name of the directory containing most of the code for the project.
- Changing the name of many related entities. For example,
SDConfig
andsd_config
becameDSDConfig
anddsd_config
. This configuration object, and other similar entities, are used throughout the main project and in all existing plugins as well. - Updating documentation. This was satisfying, because usage is more consistent and predictable. But it's a lot of work to review the entire project's documentation.
- Updating comments. Comments that aren't kept up to date with code impede understanding, so they should be kept up to date whenever possible.
- Updating tests. This impacted unit tests, integration tests, and end-to-end tests.
- Testing releases. Minor name changes can be relatively easy to test. But name changes like this affect packaging as well, which means more thorough testing of new releases than usual.
Not all of this work was critical. But neglecting any of these tasks would leave the project in an inconsistent state, right when I want more people to be able to make sense of it. And all this work is much easier to do while in the mental context of thinking about names, and the overall consistency of the internal and external project structure.

Benefits of making the change
This was a lot of work, and it's pushed back the 1.0 release by a couple weeks. But I've found it very much worthwhile. It conforms to new users' expectations, but it also served as a focused way to go through the entire codebase of the project, and all the plugins as well. I didn't fix everything I came across, because there are many less critical improvements that can wait until after the 1.0 release, if the project sees meaningful usage. But I made notes about some of these, and am more aware of which parts of the project are well-structured and which parts might be confusing to potential new contributors.
Recommendations
I compiled a list of recommendations when thinking about names, especially in the context of an evolving project where a significant name change might be necessary:
- Be thoughtful about names, and their variants.
- There are a few names in most projects that show up internally and externally. Be especially thoughtful about these names, and the variants we end up using as class names, module names, instance names, command names, and even nicknames.
- Talk (and write) about names and usage with peers and users.
- I was much better able to think about this change, and a number of previous changes, because of conversations with others about the project. Every name made sense to me because I've lived with this project as long as it's existed. But noticing which names sounded natural and which sounded awkward in conversation was a big help in understanding which changes were worth making.
- Keep a list of things to consider as your project grows.
- I'm a fan of "parking lot" issues. It's one issue where you can dump any thoughts that you don't have a clear timeline for taking action on. I scrolled through the parking lot and pulled out any question that needed to be answered before 1.0, and this change was one of them. I'm really glad I took note of it when the thought first came up, and I didn't lose sight of it before the 1.0 release.
- Here's the parking lot issue for django-simple-deploy. It's quite messy, but it keeps the overall issue tracker from becoming bloated.
- If there's a name change that would make your project more professional and current, give serious thought to making that change.
- If you're already past a stable initial release and you're managing backward compatibility, consider keeping an issue where you can compile notes about what it would take to make the change, and why you're considering it. The next time your project is approaching a major new version where you can include breaking changes, you'll be able to update the name and your project's usage.
- Let go of your history with the project, and look at it from the eyes of new users and new contributors.
- You know all the names in your project, and you've probably got some attachment to them. But which names would make sense to new users and contributors? Which names help people quickly get up to speed with your project? Which names slow people down when getting to know your project?
Conclusions
I'm really glad I made this change, and this moves the project a lot closer to the initial 1.0 release. The main thing left to do is test it thoroughly on all three OSes, which I haven't done in a while, and tighten up the documentation.
If you've got a project where naming things has been challenging, give some thought to whether you should update any names before it gets even harder.