UBC Launch Pad Documentation

# 📦 Repository Management

All project work (code or not), documentation, etc. should be done or tracked in a repository within the UBC Launch Pad GitHub organization. This page outlines general advice for how to use and maintain repositories.

# Notifications

Make sure your entire team has set up notifications correctly! This helps everyone stay in the loop on your project's progress and discussions.

# Issues and Tasks

Refer to our sprint planning guide for advice on how to manage issues and tasks in your repository!

# Documentation

Each repository should be accompanied by a set of documentation written in Markdown starting with the README, typically named README.md. Your README is the primary way for your team to showcase your awesome project to the world - take the time to make it informative and legible!

In your README, make sure you include or link to:

  • A summary of your software - in particular, briefly and succinctly outline what role your project plays or what problem it solves.
  • Usage instructions - this could be a link to a deployed website and/or how to download and get started with using your project.
  • Development instructions - make sure to cover everything that someone might need to get started with development on your project without any help. This could include development environment setup, project structure, and best practices. Since this can get quite lengthy, you can place this documentation in a separate CONTRIBUTING.md file, and link to it from your project README.
  • Project writeup - this could be a link to a blog post, a part of your README, or another file that documents your project's journey from start to end. It's a great way to highlight the work that went into your project!

# Code Tooling

Most modern programming languages have things we call "linters" or other static analysis tools to catch "obvious" mistakes and enforce code style and documentation rules. These tools often feature code editor integrations that can give you feedback on problems and even fix your code as you type!

Code tooling is generally language-specific - for example:

# Tests

Tests refer to repeatable, programmatic use of your code to assert that given input always produces the same expected behaviour and outputs. They help make sure that even when refactors or major changes are made, you can trust that most of your code base still behaves as expected, which means you spend less time chasing down obscure bugs, and allows you more freedom when improving your project's codebase.

In general, tests should be fully repeatable - given some minimal setup, the same tests should always pass, and they should not rely on your development setup or external services.

Most languages provide special tooling for testing - for example:

More advanced testing topics include "unit testing" and "integration testing", that you can do a Google search for to learn more.

Rocket 2 (opens new window) and Inertia (opens new window) are good references for comprehensive test tooling and automation.

# Testing interactions with other services

Often, you will want to test interactions with other services such as a database (PostgreSQL, MongoDB, DynamoDB, etc). The best way to do this is to run them as Docker containers locally - this makes them easy to set up and validate behaviour against. This also helps during development, since you can spin up your project locally without setting up authentication against a deployed instance and potentially running into problems with, for example, sharing a database with someone else.

In your programmatic tests, if you write to a database, make sure to include "teardown" steps after each test (to revert any changes a test makes, to avoid affecting other tests).

# Repository Templates

GitHub lets you define templates (opens new window) to help you standardize the format of your issues and pull requests.

You can refer to example templates used at Launch Pad (opens new window) for ideas!

# Ignoring Files

Include a .gitignore file (opens new window) to reduce the chances that people push unwanted content; in particular, it is highly recommended to add the following to your .gitignore:

  • Config files produced by common IDEs, like IntelliJ, Xcode, Android Studio, and so on.
  • .DS_Store files, which are produced by MacOS.
  • Compiled assets, such as Python's .pyc files or bin output.

# CI/CD

CI/CD, or "Continuous Integration" and "Continuous Deployment", refers to the automated processes that are designed to run tasks for every change that is pushed to a code repository.

Launch Pad currently recommends GitHub Actions (opens new window) for setting up CI/CD pipelines. To get started, refer to:

# Continuous Integration

You should have a continuous integration system in place to ensure that new code is tested and meets team standards.

Your continuous integration (CI) process should run:

# Code Coverage

Most code testing frameworks provide ways to export code coverage results. Code coverage refers to the lines of code that are run during tests, and allow you to verify you are actually testing your code - for example, see the Inertia coverage report (opens new window).

We currently recommend Codecov (opens new window) for aggregating and viewing your code coverage. The Sourcegraph browser extension allows you to view this coverage on GitHub (opens new window) as well.

# Continuous Deployment

Nowadays, continuous deployment for smaller projects typically happen externally in other services - see our recommendations in deployment options.