# Overview GitHub is a cloud-based platform to facilitate distributed version control using [[Git]]. Distributed, here, means that teams can all work on their own versions of a project on their local computer, and handle storage of these changes and merging of changes through a central GitHub-hosted repository. GitHub also provides other features, such as access control, issue tracking, continuous integration pipelines, and project management tools. Here, I outline several key features of GitHub and best practices for working with them. # Issues GitHub allows project maintainers and anyone else with access to add [issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues). An "issue" is something like a "ticket", it is some requested change to a project. It could be a bug that needs fixed, a feature that should be developed, or a question that needs resolved. When adding an issue, be as clear and concise as possible, and provide example code or output of the error. Add appropriate tags to the issue, which help with choosing which issues to prioritize. Where appropriate, assign issues to a project maintainer with the relevant expertise. Each issue is automatically assigned a number. This number can be referenced elsewhere in the repository using the \# character, such as `#42`. Link between issues, and from issues to pull requests whenever possible. # Pull Requests Directly merging changes to the main branch is bad practice, it runs the risk of introducing breaking changes. Instead, merges should always be made using [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) (or PR). When changes are committed to a branch, and those changes pushed to the GitHub repository, you can merge these changes by submitting a PR. When submitting, you should include a clear description of the changes, add appropriate tags, and assign an appropriate reviewer. Then, the pull requests acts as a thread in which the changes can be reviewed and discussed and additional changes made. The PR feature of GitHub includes features for conducting code reviews and resolving merge conflicts. As best practice, do all development in a separate branch, and always merge changes to the main branch using a PR, even when on a solo project. # Forks When there is a public repository on GitHub, you can make a copy of it by using the [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) feature. A fork of a repository makes a separate repository owned by you, but from which changes such as pull requests can be submitted to the original (upstream) repository. # Resources - [GitHub documentation](https://docs.github.com/en/get-started/quickstart/hello-world) # Tips and Best Practices - **Do not commit API keys**. They will be public for everyone to see and use, and can be difficult to completely expunge from a repository's history. Consider storing your keys in your local environment. This same advice goes for any sensitive information. # Trivia - GitHub was acquired by Microsoft in 2018 - The mascot for GitHub is the "OctoCat", a cat-octopus creature with 5 tentacles