Github “Operative System”

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