📦 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.

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.
  • For example, the ubclaunchpad/inertia README (opens new window) includes a section on what the project does, its features, and who might want to use it.
• Usage instructions - this could be a link to a deployed website and/or how to download and get started with using your project.
  • For example, the ubclaunchpad/ubclaunchpad.com README (opens new window) includes a link to the deployed website and the project's USING.md (opens new window), which covers some tips on how to use the website.
• 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.
  • For example, the ubclaunchpad/ubclaunchpad.com Contribution Guide (opens new window) and ubclaunchpad/inertia Contribution Guide (opens new window) both include detailed instructions on how to get set up and start hacking on the project.
• 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!
  • For example, the ubclaunchpad/food-doods README (opens new window) documents the team's ideas, pain points they encountered, design mockups, and more.

Enforcing Standards

You should enforce a clearly defined set of standards for your code; in particular, this should both be listed in your documentation and enforced during the build process.

Most modern programming languages have linters or other static analysis tools to catch "obvious" mistakes and enforce code style and documentation rules, and running these alongside your tests is highly recommended. Additionally, many languages, including Python and golang, have standardized code styles and tools to enforce them, such as pycodestyle and gofmt.

Adding a pull request template will increase the likelihood that pull request descriptions contain the information you and other maintainers need during the review process.

Include a .gitignore file to reduce the chances that people push unwanted content; in particular, it is highly recommended to include config files produced by common IDEs, like IntelliJ, Xcode, Android Studio, and so on. It is also best to ignore compiled assets, such as Python's .pyc files.

It is highly recommended that you provide Docker and docker-compose files as a means of ensuring simple setup and standardized development/build environments.

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 automated tests, linters, code style enforcers, and anything else that can be automated and help maintain high code quality. Tests in particular 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.

CI Platform

Launch Pad currently recommends GitHub Actions (opens new window). To get started, refer to:

• official Actions Workflows documentation (opens new window)
• Actions Workflows in use at Launch Pad (opens new window)

Code Coverage

Code coverage of tests in particular is very valuable to collect during your CI builds. It's particularly recommended to enforce a minimum threshold for code coverage (though this does not guarantee that you have good tests!). Sites that provide code coverage dashboards are a convenient way to summarize this data; we currently recommend Codecov (opens new window).

Ideally documentation about the inner workings of the tool should lie as close to the code it describes as possible.