Skip to content

Collaboration

Jump to bottom
Athi Fongoqa edited this page Feb 8, 2022 · 2 revisions

GitHub Collaboration Guidelines

Intro

This document provides an overview of GitHub collaboration we should try implementing moving forward for legibility and coherence with regards to our development lifecycle.

Repositories

If you have to create a repository, use the following naming conventions:

  • Use lower case letters.
  • Use dashes instead of white spaces or underscores.
  • Be specific. You may find you have to differentiate between similar ideas later. As an example use: "sales-rest-service" instead of "service" or "rest-service".

README files

Please keep in mind that you have to write a README.md file about your project and upload it to your repository.

Here are 2 useful guides that explain some best practices about README files:

  1. https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/
  2. https://bulldogjob.com/news/449-how-to-write-a-good-readme-for-your-github-projec

Collaborating on the README file is encouraged.

Git

Git is a version control tool. Working with version control means that you can revert back to previous stages of the code at any time, as well as having an history of the changes made to the repository. Here you can find a a git cheat sheet with some of the commands available, but you will probably only frequently use:

git add 
git commit
git push 
git pull 
git checkout

Pull Requests

When collaborating on a repository, a general rule is not to push changes directly to the main branch. To add changes to a repository, you have to:

  1. Create a new branch.
  2. Commit your changes to the newly created branch.
  3. Create a pull request in GitHub to merge the changes in the main branch or another branch.
  4. Wait for the review of at least 1 of your teammates.
  5. Merge the changes.

For a better overview of pull requests and collaboration on GitHub, you can take a look at this YouTube video.

Commits

For every piece of code that you push to GitHub you have to write a commit message. Keep the commit message short and informative. You can find a quick overview of how to write commits in this YouTube video, or the full guidelines here.

The full commit described by conventional commits looks like this:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
  • The available types that you can use are:
🔧 fix - fixing a feature that a user accesses/sees

💎 feat - adding a new feature that a user accesses/sees

⚙ build -changes that affect the build system of the production code or external dependencies (example scopes: gulp, broccoli, npm)

🛡️ chore - changes in support or grunt tasks; no production code change

🚀 perf - changes that improve performance

🔌 ci - work relating to the ci/cd pipeline

🏗 infra - work relating to the delivery infrastructure

📝 docs - changes to the documentation

🍸 style - changes in the code’s formatting and general style that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)

🧹 refactor - cleaning the code after testing codebase, it neither fixes a bug nor adds a feature

🧪 test - adding missing tests or correcting existing tests in the codebase

⏮ revert - reverts a previous commit
  • The scope (not required) can be used to add information about the type, e.g.:
style(homepage): add padding

  • The description is a short message written in imperative.

  • Body and footer are really not required, but if you want to write them you can find their specifications in the full guidelines online.

⛔ Basically, we should avoid commit messages such as 'fix' or 'now it works' at all costs.
Clone this wiki locally