Projects are not just the end result
Looking at git-grab and it's Makefile as an example

What real is a project? In this post I will use the simpler example of git-grab to try explain how projects grow really complex before you even know whats happened. If you have not read the first post Git-grab, a side project introduction, here is the short introduction to what it is. Git-grab is a python command line tool for managing paths to git repo's on your local machine. It can be installed by using pip install git-grab. In the last two sentences I point out two things which are important for context here. Git-grab is install using the pip which is a python tool and the command line tool is written in python.

Everything about the project is centered around python and the end result that is consumed by the end user is python. That's why in this post we are talking about the Makefile. The best why I can think of to describe what the Makefile is would be. A Makefile contains targets which when invoked preforms common tasks used during the creation of the project. 

What does invoke common tasks real mean. As an example there is a make target called release, this simple target will release a new version of the package when its called. The example of doing this is shown in below.

make release

But what does that example look like when not using the Make target.

rm -fr build/
rm -fr dist/
rm -fr .eggs/
find . -name '*.egg-info' -exec rm -fr {} +
find . -name '*.egg' -exec rm -f {} +
find . -name '*.pyc' -exec rm -f {} +
find . -name '*.pyo' -exec rm -f {} +
find . -name '*~' -exec rm -f {} +
find . -name '__pycache__' -exec rm -fr {} +   
rm -fr .tox/
rm -f .coverage
rm -fr htmlcov/
rm -fr .pytest_cache/
rm -fr site/
VERSION := v$(shell python setup.py --version)
python setup.py sdist
python setup.py bdist_wheel
twine upload dist/*
@echo "pushing tags"
git tag $(VERSION)
git push --tags

As seen it's a bit longer. So it's like making little scripts to do the repetitive work needed to manage a project. Yes but not really it's for one not written in python but does require maintenance and as a project maintainer that means you have to know how it works. From looking at the step that are actually been made we can see a few more things. There are build in command line commands been used find & rm, python it's self is used and other applications such as twine & git. If you were to look through the Makefile you would see other applications been referenced, mkdocs, pip, tox, black and pytest. 

What I am badly trying to get across is output of a project is only a very small part of what goes into the project. As a developer you need to have an understanding of all the moving parts in and around a project not just the ones that you enjoy. There might be pipelines that automate more stuff for you. There can be build system. How is the documentation created? Is there promotional materials, a website or governmental requirements that need to be maintained. Of course in large companies there will be people to do this work so you can just focus on the programing but must likely your working on large projects. These large project will span multiply teams, repos and even projects.

It could happen that one of your required build tools for your project is maintained by your team. The end deliverable is a very small part of the work that goes into a project. Software is complex and the easier it's for the user the more complex it is to create. When you are running the Makefile targets you are the user, so ask your self could this be easier and when you say yes think about what changes would be required to make it easier for the user.

So what's the point of this rant. Not much only that no matter what project, language or system you think you will be using, there will be more that you need to do. More that you need learn. The more you automate, which you should, the easier it gets for the user, let that be other members of the team or the future you. But be very surprised if the automation is in the same ecosystem that your project exists. 

Don't get me wrong this is not a bad thing but you have to be ready and understand for every one job on a project there is ten more jobs that work to support it.

Projects are not just the end result
Jim Fitzpatrick 5 April, 2021
Share this post
Our blogs
Archive
Sign in to leave a comment
How to use Git revert
Let git undo your mistakes