Github “Operative System”

9 min readApr 21, 2021

I called this “Github Operative System” because this small meta-guide’s intent is not so much to describe Github usage in great detail but to provide the reader a convenient and shared method or a system indeed to “operate” on a project professionally, in a teamwork context.

Everything that follows represents just one way to intend and use some Github features, and it’s meant as inspiration only.
Every developer and every company will find what’s the best fit for their needs and usage.

🚀 Account

Github account is personal, you should not use your company mail.

Moreover a lot of services lets you login with Github and if you already have accounts created this way, you will have to logout from your company account and login with yours, then log back with the company one… very messy.

“Organization” is the way Github handles this problem and spare us the pain of having 2 different accounts.

Anyway if you used your company mail you can always change it from settings > email

But every time you change the mail you will loose all the history of your work. (it’s bad for you)

🔧 Settings

When invited in our “Organization” you will be asked to activate 2FA (2 factor authentication) for security reasons. settings > security

✨ Repo

creation: a company designed git manager will create the repo for you. You will decide the name together. If the name has more than one word, it will have hyphens, something like my-project-web.

If a monorepo structure makes sense for the project, it will be decided at this moment.

admin: the git manager will make someone admin for the repo. The admin(s), from that moment on, will be responsible for that repo.

rights: repo admin will have to decide roles for the others invited to contribute. Repository access for each permission level.

readme: repo admin will HAVE TO write a README.md file in markdown syntax that tells who is the repo admin and who is the project manager, what the repo is about, how to install and run the project, the tech stack and how to contribute.

about: a description with tags will have to be provided.

How to Write a Good README File for Your GitHub Project — link

📝 Documentation

The developer have to create and maintain the proper project documentation versioned with code, before writing the code even if the solution is not final. This because it’s easier to reason about something already documented and it’s easier to write documentation incrementally that having to write everything at once, with the risk to forget some detail.

for a db with a ERD diagram file from draw.io
for an API with the .yml file from open-generator
for a specific flow with a flow chart file from draw.io (eg. authentication flow like oAuth or SAML)

🗃️ Branch naming convention

main Github default branch - always contains stable version of code

dev main branch for developers - contains latest working version of code, from here feature and bugfix branches are started

test version for testers - if dev code is changing too fast to be tested accurately, then this branch is updated with groups of updates on regular basis to be tested

demo for the customer - this branch contains unfinished product demo for the customer

prod current production code - this code is the one officially running on the server, in the container, on mobile etc etc.. at any given time

💄 Code conventions

Don’t use personal indentation or spacing system. Just use a convention.

If you’re writing javascript you can use Prettier with this .prettierrc configuration file on your project's root folder:

{
  "singleQuote": true,
  "endOfLine": "lf",
}

Prettier — link

🙈 Git ignore

A file called .gitignore in the root of your project gives you the possibility to exclude from versioning specific files (.env) , folders (node_modules) or patterns of (private-code/**/*.js)

⬆️ Conventional Commits

The Conventional Commits specification is a lightweight convention on top of commit messages.

This makes easier to use automated tool when releasing the code in order to keep track of the changes in a particular release, bump up the version number accordingly or even notify about breaking changes.

Conventional Commits — link

🔀 Git flow

When more devs are working on the same repo and/or when multiple features are being developed using a systematic branching model is crucial in order to avoid confusion and unexpected code arrangement.

The most popular branching system is “Git Flow”, so popular that git CLI has its commands embedded and ready to be used. This system makes you create new branches for every feature, that you implement. At the end of the iteration this branch will be automatically merged into the main branch and deleted.

Useful commands:

see Git Flow help git flow -h (take a look)
create new flow: git flow <branch-type> start <name>
merge and delete flow: git flow <branch-type> finish <name>
possible branch types: feature, bugfix, release, hotfix, support

You have to use types properly and a meaningful name of 1–3 words divided by hyphens (-)

When creating a branch about an issue you have to use the issue number, like this:

# start branch about issue #254
git flow bugfix start 254# close
git flow bugfix finish 254

git-flow cheatsheet — link
Original article by Vincent Driessen about branching model — link

🐛 Issues

Anyone who has access to the repo and has the rights can open a new “Issue”, that’s why it is important having a template: so the user that is opening the issue has a guide that makes easier for him to write relevant info and for the developer to read and understand the problem fast.

Create a GitHub Issue Template — link

It’s important that every part involved in the product is present and continuously active on Github:

developers will manage code, issues, releases… everything
testers will deal mainly with issues and approaching milestones
project designers will solve process issues and they should version documentation (flows, diagrams) whenever possible
UI and UX designers will solve graphic inconsistencies and requests and they should version important documents about design system, colors and typography
architecture designers and sysops will document the infrastructure with code
project managers will overlook everything, from commit comments to issues, they will decide about milestones and issues attached to milestones (de-facto defining issues priorities)

The common ground anyway will be the “Issues”. Everybody can open them and every issue can be addressed to everybody, project and UI designers too.

Repository is at this point a pivotal tool where everybody can store their work, find or ask for information making the process smooth and fast.

Asking and answering always on Github information will be always available.

The issue opener ALWAYS has to check if a similar issue about the same object was already opened searching for it on the search bar.

The developer that takes charge of the issue has to list himself as assignee. This will write a message in the issue history that will mean itself that the issue is being processed.

🚩 Milestones

A milestone defines the approximate timing of the releases, so they are useful to define when a fix for an issue is due.

The project manager with the help of the developer has to decide which of the following milestone will contain the resolution of the issue.

This eliminates the need of priority itself, in fact they identify the priority of a specific issue by saying that the solution will have to be found by the time a milestone is reached (it can be binded to a date)

🏷️ Labels

Labels are THE way to sort and manage issues.

Probably most of the labels you will ever need are already set up for you for every new repo of the organization.

If you need to create, delete or modify labels you can browse to repo > issues > labels and use the button New label or the edit or delete link next to each existing label.

A label holds a concept, always remember to stop and think to the implications of using that concept at play with the other preexisting labels.

Is that concept overlapping another one? mobile vs android
Is the new label describing completely the new concept or other labels will need to exist to better represent that domain? server will need client or similar?

and so on.. keep in mind that it’s often difficult to delete a label already used without compromising the readability of the past and the future of the project’s issues.

🚸 Usage

The labels has to be placed by the developer as soon as possible, even if no bugfixing activity is currently engaged.

When a developer has a question about the issue should ALWAYS use the issue response on Github and NEVER Slack or email in order not to hide information to others.

A typical example is when the issue is opened with insufficient informations, in this case the developer should label the issue with need more info and explicitly comment, mentioning who opened the issue in the first place (with @<name>) and asking for the missing parts.

All the discussion about the issue has to take place on Github. You have to remember your peers to answer there, linking the project documentation.

When a developer starts to work on an issue using Git Flow at the first commit a notification message will appear on the issue history. The same will happen for every commit and for the branch closing.

Then the developer closes the issue and adds ready to test label.

When the tester has tested the closed issue has to choices:

the problem is solved and ready to test label will be removed
the problem is not solved, ready to test label will be removed and the issue re-opened with the Reopen issue button

This way the state of the issue is always clear to anyone.

📸 Releases

When all the issues of a milestone are closed or when a certain date arrives it’s time to release a new version of the code. To do so the developer or the project manager can create a new “Release” from the repo’s page

Version, title and description has to be written like this:

When building an artifact like a Android .apk or a build zip or a binary, the file it has to be attached using the proper drag n'drop area. This way testing the latest release will be much more fast and versions tracking will be effective.

Thanks to the use of “conventional-commits” and “Github Actions” writing the release description and building the binaries can be automated activities.

Github Actions — link

An even better option for our repository would be using semantic-release to automatically bump the version and create the release.

Semantic Release Automation — link

📌 Repository template

A nice strategy is to completely setup a repo adding issue templates, git-actions, branches, files and folder structures and then creating a template repository. Later you will spin off a new repository with the same features effortlessly and you will be ready to make the latest tweaks and start pushing really good code!

Creating a template repository — link

🥅 Best practices

everything is documentation:
- README.md
- repo description
- branch names
- commits message
- issue comments
- release description
- documentation that you are writing for this project
work on one thing at a time
make small, frequent, commits at least locally
at the end of the day or when you’re done push to repo
NEVER commit configuration files like .env files with keys
don’t commit dependencies or generated files
if you have broken code you…
- preferably stash it
- alternatively commit locally or
- commit and push if you’re in a branch where working alone
- but NEVER commit and push it to main branch
with the help of conventional commit write meaningful commit messages possibly use proper emoji too
use .gitignore and prettier.io
don’t mix “refactoring” with a new feature code but commit those activities separately
if you see dead code or unused files double check and then delete it, keep it clean