Skip to content

On-boarding

This page provides step-by-step onboarding guidance for interns and employees who will be working on software development projects at Bitosis.

Editor

Real Programmers

Feel free to use whichever editor or IDE you prefer. But it's important that we maintain a consistent coding style, which is why our projects come with an .editorconfig file. EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs. Some editors come bundled with native support for EditorConfig, but others require you to install a plugin. Head over to editorconfig.org to find the plugin for your editor.

HTML / CSS / JavaScript / Web API

Developing websites and web applications always involvs writing or modifying HTML, CSS, and JavaScript code. MDN Web Docs is a great resource for web developers, as it contains documentation for all web technologies, including HTML, CSS, JavaScript, and Web API. Everything you need to know about web technologies you can probably find on this website. Use the search field on the top to try this out for yourself. For example, try searching for "html body" or "querySelector" and click on one of the results. The documentation on this website is very clear and comes with plenty of examples. Use this website as a reference for web technologies, but you can also find plenty of tutorials in case you want to know more about a specific web technology:

Python

Python

Python has become a popular programming language. If you're new to Python, the following sites are good resources to learn the basics:

  • The Python Tutorial

    This tutorial is great if you already have some programming experience. It's to the point and gets you up and running quickly.

Coding conventions

PEP 8 provides coding conventions for Python code. It is fairly common for Python code to follow this style guide. Our aim is for all our Python code to follow this style guide, so it's important to familiarise yourself with the guidelines.

Similarly, PEP 257 provides coding conventions for Python's docstrings, which are strings intended to document modules, classes, functions, and methods.

Virtual environments

Most of our projects come with a Docker development environment, which is essentially a virtual environment preconfigured with all the tools needed to run the project.

When working on a Python project outside a Docker container, however, it's best practice to always work inside a Python virtual environment. They allow you to manage separate package installations for different projects. But manually managing virtualenv's for each project quickly becomes a chore. This is where Pipenv comes in. Pipenv is a tool that automatically creates and manages a virtualenv for your Python projects.

Django

Many web projects are based on Django, which is a Python framework for developing web applications. If you're new to Django, Django's own tutorial is a good way to learn Django:

Wagtail

Some websites are built with the Wagtail content management system, which is built on Django. If you're going to work with Wagtail, you should familiarize yourself with both Django and Wagtail:

Git

Git

We use Git for version control. If you're new to Git or version control, we recommend reading chapters 1 through 3 of the excellent Pro Git book to get started.

Git workflow

Different teams use different Git workflows. Our Git workflow is as follows:

  1. Pull to update your local master/main branch.
  2. Make your changes in a feature branch. Try to keep your changes in a single commit (see Changing the Last Commit).
  3. Rebase on the master/main branch frequently to incorporate upstream changes.
  4. Interactive rebase (squash) your commits. Ideally only one commit will end up in each merge request.
  5. Push your feature branch to the remote repository on GitLab.
  6. In GitLab create a merge request from your branch.
  7. Have someone else review your merge request. This may lead to discussions and updates to the code. When updating your code, just push your changes to the same remote branch. The merge request will be updated automatically.
  8. Once the merge request is accepted by the reviewer, merge your work into the master/main branch and delete your feature branch.
  9. Go to 1.

Do make useful commit messages

Creating insightful and descriptive commit messages is one of the best things you can do for others who use the repository. It lets people quickly understand changes without having to read code.

Clone a project

Now that you know the basics of Git, you should be able to clone one of our GitLab projects. When you're viewing a repository in GitLab, you should see a "Clone" button in the top-right corner. Use the "Clone with SSH" option if you plan to work on a project. You'll first need to generate an SSH key pair for this to work.

Docker

We created Docker development environments for most of our projects. A Docker development environment allows you to get a project up and running on your local machine without hassle. It comes with all the tools you need to start working on a project, so there's no need for you to install or configure anything on your computer. Using a Docker development environment also means that the project works the same way for anyone working on the project (making "it works on my machine" a thing of the past). You only need to install Docker Engine to get started:

After installation on Linux or macOS you can add your user to the docker group so that you don't need to use sudo to run Docker commands:

sudo adduser $USER docker

The new group isn't effective until you log out and back in. You can also simply restart your computer. You should then be able to run docker commands, for example:

docker run hello-world

You should see a message "Hello from Docker!".

Shell scripts and Windows

Most of our projects assume you run a Unix-like operating system (e.g. GNU/Linux or macOS), hence you'll find some Unix shell scripts. For example, the projects that have a Docker development environment come with the Shell script docker/start.sh that is used to start the development environment.

You'll need to install some flavour of GNU/Linux to run Shell scripts. Ubuntu is a very popular and easy to use GNU/Linux distribution and there are several options to install Ubuntu on Windows. Pick one of these two options:

  • Install Ubuntu on WSL2 on Windows

    Windows Subsystem for Linux (WSL) allows you to install a complete Ubuntu terminal environment in minutes on your Windows machine, allowing you to develop cross-platform applications without leaving Windows. You'll need to select Ubuntu 20.04 LTS, as the latest version of Ubuntu on WSL doesn't work well with Docker.

  • Run Ubuntu Desktop on a virtual machine using VirtualBox

    One of the easiest ways to try out Ubuntu Desktop on a virtual machine. VirtualBox is a general purpose virtualiser that is available across Linux, Mac OS and Windows. It's a great way to experience Ubuntu regardless of your current operating system.

Once you have Ubuntu up and running you can install Docker and Git on Ubuntu.

You can now start working on a project. For example, open the Terminal in Ubuntu and try this:

# Change to your home directory
cd

# Create a directory for all your projects
mkdir Projects

# Change to your projects directory
cd Projects

# Clone a repository to work on
git clone https://gitlab.com/getgnulinux/getgnulinux.git

# List all your projects
ls -l

# Change to a project directory
cd getgnulinux

# List project contents
ls -l

# Read the README (use Up-Down buttons, press `q` to exit)
less README.md

# Start the Docker environment
./docker/start.sh

Clean up Docker images

Intensive use of Docker for development can fill up your storage space with Docker images pretty quickly. To free up some space, you can run these commands.

To delete all unused images, run:

docker system prune -a

To also delete volumes (databases, etc.), run:

docker system prune -a --volumes

Credits

  1. xkcd comics Real Programmers, Python, Git, XKCDE
  2. Commit Often, Perfect Later, Publish Once: Git Best Practices. https://sethrobertson.github.io/GitBestPractices/