{"id":21977827,"url":"https://github.com/oakvilledynamics/flight-rules","last_synced_at":"2026-05-05T02:33:07.962Z","repository":{"id":49309272,"uuid":"466693106","full_name":"OakvilleDynamics/flight-rules","owner":"OakvilleDynamics","description":"OakvilleDynamics Git/GitHub Flight Rules for repositories and code","archived":false,"fork":false,"pushed_at":"2022-07-24T04:44:21.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-28T03:43:08.856Z","etag":null,"topics":["documentation","getting-started","git","how-to"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OakvilleDynamics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-03-06T09:37:06.000Z","updated_at":"2023-02-28T21:10:06.000Z","dependencies_parsed_at":"2022-09-11T23:22:14.977Z","dependency_job_id":null,"html_url":"https://github.com/OakvilleDynamics/flight-rules","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OakvilleDynamics%2Fflight-rules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OakvilleDynamics%2Fflight-rules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OakvilleDynamics%2Fflight-rules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OakvilleDynamics%2Fflight-rules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OakvilleDynamics","download_url":"https://codeload.github.com/OakvilleDynamics/flight-rules/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245040141,"owners_count":20551292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","getting-started","git","how-to"],"created_at":"2024-11-29T16:16:35.005Z","updated_at":"2026-05-05T02:33:07.908Z","avatar_url":"https://github.com/OakvilleDynamics.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Oakville Dynamics FRC Robotics Git/GitHub Flight Rules\n\nThis document will cover all the basic usages of Git, and the platform GitHub, as well as general practice implementations and keeping good documented code and treating such repositories as cleanly and orderly as possible.\n\n## Table of Contents\n\n- [Oakville Dynamics FRC Robotics Git/GitHub Flight Rules](#oakville-dynamics-frc-robotics-gitgithub-flight-rules)\n  - [Table of Contents](#table-of-contents)\n  - [FAQ](#faq)\n    - [Q: What is this document?](#q-what-is-this-document)\n    - [Q: Can there be a section on _x_?](#q-can-there-be-a-section-on-x)\n    - [Q: Will there be any coverage on using a Git terminal or a Git client that has a GUI?](#q-will-there-be-any-coverage-on-using-a-git-terminal-or-a-git-client-that-has-a-gui)\n    - [Q: I notice an error, can I fix it?](#q-i-notice-an-error-can-i-fix-it)\n  - [Basics of Git](#basics-of-git)\n    - [What is Git?](#what-is-git)\n    - [How do I save changes?](#how-do-i-save-changes)\n    - [What is GitHub?](#what-is-github)\n    - [How do I work with other people?](#how-do-i-work-with-other-people)\n    - [How do I get my code to be on the main branch?](#how-do-i-get-my-code-to-be-on-the-main-branch)\n    - [Simplified definitions](#simplified-definitions)\n  - [General Process from start to finish](#general-process-from-start-to-finish)\n  - [Commits](#commits)\n    - [Structure](#structure)\n    - [Writing a good commit](#writing-a-good-commit)\n      - [Examples of good commits](#examples-of-good-commits)\n      - [Examples of bad commits](#examples-of-bad-commits)\n    - [When to make a commit](#when-to-make-a-commit)\n    - [Commit != Push](#commit--push)\n  - [Branches](#branches)\n    - [Managing branches](#managing-branches)\n    - [When to merge a branch](#when-to-merge-a-branch)\n      - [Pull Requests](#pull-requests)\n      - [Merging directly into main](#merging-directly-into-main)\n\n## FAQ\n\n### Q: What is this document?\n\nThis document provides a structure for anything that you should do when operating Git, GitHub, or any codebase within the organization.\n\nFollowing this document or the guidelines of this document when things do go wrong can help you in the process of things breaking, or if you want to sharpen your Git skills\n\nThere will also be examples used from archived repositories from competitions past to ensure consistency.\n\n### Q: Can there be a section on _x_?\n\nThere can if there is enough of a reason to include in the basic Git Flight Rules or if is important and not currently covered by the current set of Flight Rules.\n\nFor you to suggest a section:\n\n1. Create an issue on the repository\n2. Write a descriptive and source of this new added section\n   1. If you already have made the additions and you want to submit them, you can submit a pull request and have the changes review\n3. Wait for an official and orderly response to include the new section into the Flight Rules.\n\n### Q: Will there be any coverage on using a Git terminal or a Git client that has a GUI?\n\nThere will be basic inclusions of getting basic operations on how to deal with Git and GitHub in a specific client. For the time being, this set of flight rules will only have documentation on how to use GitHub Desktop, which is a free Git client that anyone can download on Windows and macOS.\n\nBasic commands will also be included on how to run basic commands into a Git terminal as a reference.\n\n### Q: I notice an error, can I fix it?\n\nCreate an issue, if you want to fix it yourself you can make a pull request. Make sure you lint the project with `markdownlint` to ensure formatting documents.\n\n## Basics of Git\n\n### What is Git?\n\nGit is a tool that allows for code to be saved in a manner where there is versioning, such as `v0.1`, `v0.2.1`, etc., and is self containing. No extra folders that have to be renamed, it does the job for you.\n\n### How do I save changes?\n\nWhen you want to save a change that you have made, it is called a `commit`. A commit tracks the changes that you have made to what was previously there, and keeps a running history of every single change on every single line.\n\nSaving with Ctrl+S/⌘+S just saves normally, this does not save in Git. You need to tell Git to commit those changes, therefore it is saved in Git.\n\n### What is GitHub?\n\nGit is merely the tool, but GitHub is the \"Google Drive\" of code, where you can share your code with others and work on it simultaneously. This location is called a `repository`.\n\nOnce your code is committed, you can `push` your changes to GitHub, where everyone that has access to your code can work off of your changes.\n\n### How do I work with other people?\n\nTo have others code on your local machine to test and tweak, you can `pull` from GitHub, which just pulls all the changes made to your computer.\n\nAll you need to work with people on GitHub is a GitHub account.\n\nThink of a tree, there are branches on a tree, it all stems back into the main branch that is the source of the whole tree. This can be translated into a repository, a `branch` is a clone of the main branch on the tree, or another branch entirely, and is separate. This is helpful when working with others as new features or fixing bugs can be tested in its own sandbox.\n\n### How do I get my code to be on the main branch?\n\nYou can combine branches back into the main branch either with a merge or a pull request.\n\n### Simplified definitions\n\n- Git\n  - A special tool that saves all changes for all code written from history\n- GitHub\n  - Google Drive for code, you can share and collabrorate online with just sending a link and browse others code for inspiration and brainstorming\n- Commit\n  - A savepoint for code\n- Push\n  - Submitting your code to a GitHub repository, so others can look and collaborate on your changes\n- Pull\n  - Retrieving changes made from a GitHub repository, if someone were to make changes and you want to be current and up to date on what you are working on\n- Repository\n  - If GitHub is Google Drive for code, A repository is a Google Doc for code\n- Branch\n  - Separate copies of the main code, can be used to add new features, fix bugs, or other major changes\n\n## General Process from start to finish\n\nThis section outlines what actions should be done when clocking in to work and clocking out when work is finished for the day.\n\n1. Pull changes from current robotics repository\n2. Ask around what everyone is working on as well as what needs to be done for you if progress has been made, check chats if there has been mentions of you or code to get working or added\n3. Make changes\n4. Commit changes\n5. Repeat steps 3-4 until packing up\n6. Push all changes to repository\n\nOnce you have pushed everything to the repository, others are able to view work and can work with your code if you are absent from a build session or working remotely.\n\n## Commits\n\nCommits are logs of changes that are submitted. Each commit has a title, a hash of the commit, and optionally a description. Once a commit is finished you can push it to a remote repository, such as GitHub if you want others to view your code. The process of making a commit involves these steps:\n\n1. Saving work in your editor/IDE if not already saved\n2. Open your Git client\n3. Add your files to staging\n4. Write a title and description of the work that you did\n5. Commit changes\n6. Push changes\n\n### Structure\n\nEach commit has a defined title and an optional description. This will contain all notes, changes, fixes, removals, etc. to not only yourself, but other contributors.\n\n### Writing a good commit\n\nA good title in Git when looking at a list of changes is helpful for others to look at without diving into the codebase to look at each line that was modified. A title can include a general overview of what changes were made in a condensed form.\n\nA good commit title should:\n\n- Be 72 characters or less\n- A small but general summary of changes\n- Does not end with a period\n- Use the commit message to list in detail how changes are made.\n- Capitalized the beginning of the title\n\nIt should also make sense in a sentence, such as: If applied, this commit will `\u003csubject line here\u003e`\n\nFor example, A commit may be titled `Update time function, Gradle libraries, refactor async methods`.\n\nA good commit should also have a good message of what work has been completed. If someone were to go to a single commit but didn't want to look at all the code that has been added, modified, or removed, this is where the message of a commit comes in.\n\nA good commit message should:\n\n- List in-depth how changes have been made, such as why a change has been made\n- Bullet points can be used to list changes as well\n- Capitalize each bullet point and paragraphs\n- Free of gramatical and spelling errors\n\nIf a commit referrs to an issue, you can add a reference to a commit, and with GitHub there can be a link that resolves to an issue.\n\n#### Examples of good commits\n\nEach section of new commits will show a link to the specific commit on the GitHub repostitory, as well as including the title as well as a description on what the commit is in detail.\n\nThis can be both informative as well as accurate to include as good enough detail as what could be changed for a better commit.\n\nCommit quality is subjective and can change from one person to the next, but a general rule of thumb is more detail in the commit the better.\n\n[OakvilleDynamics/FRC-Robot-Code @ main+b079758b82340762c84e5c892e3d886e596baba9](https://github.com/OakvilleDynamics/FRC-Robot-Code/commit/b079758b82340762c84e5c892e3d886e596baba9)\n\n\u003e **Changed power values, started combine reworking, more changes**\n\u003e\n\u003e - Added constants for values that will never be changed, such as motor values for the port\n\u003e - Manifested Combine subsystems and commands\n\u003e - Reduced the maximum power output by the drive motors to 40%, or 0.4\n\u003e - Added some debugging statements for joysticks on the contollers\n\u003e\n\u003e The combine subsystems and commands do not work as of yet. The tank drive might also be changed out to another type of drive.\n\n| Why this commit is considred 'good'     | Why this commit is considered 'bad'                                                                  |\n| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| Decscriptive title                      | Title does not have proper formatting                                                                |\n| Outlined all changes made into a commit | Bullet points are not needed or misplaced unless rapid-firing minor changes or outlining new feature |\n| Included a general summary              |                                                                                                      |\n\n[OakvilleDynamics/FRC-Robot-Code @ main+4fc20f1eacd7f24ec28d91ea85d9e6c8477f7e79](https://github.com/OakvilleDynamics/FRC-Robot-Code/commit/4fc20f1eacd7f24ec28d91ea85d9e6c8477f7e79)\n\n\u003e **Major changes to controls, pneumatics, and combine systems**\n\u003e\n\u003e AUTHORING CREDITS: Flamingpuffins \u003cflamingpuffins@gmail.com\u003e\n\u003e\n\u003e - Controls are now working properly, as it was only grabbing the release state, not the pressed state\n\u003e - All pneumatics (Ramp and Button Press) are working properly\n\u003e - Inverted and slightly sped up the combine spin\n\u003e - Changed the combine port\n\u003e - Added some basic debugging to the subsystems\n\u003e - Formatting fixes\n\u003e\n\u003e There is some unfinished code that exists in the TankDrive as a speed curve, this is left in for future working\n\n| Why this commit is considered 'good'                                       | Why this commit is considered 'bad'             |\n| -------------------------------------------------------------------------- | ----------------------------------------------- |\n| Title introduces the changes properly                                      | Title is a bit vague                            |\n| Consise bulleted list                                                      | Some of the list could be written as paragraphs |\n| Outlines possible future fixes or other changes that need to be made       |                                                 |\n| Mentions proper authoring credits if someone else did not write the commit |                                                 |\n\n[OakvilleDynamics/ohsrobotics-gameelement-2020-2021 @ main+ce6691de5e4d6e9645453f6234126ba30baecf82](https://github.com/OakvilleDynamics/ohsrobotics-gameelement-2020-2021/commit/ce6691de5e4d6e9645453f6234126ba30baecf82)\n\n\u003e **Changing behavior when button is pressed early and minor changes**\n\u003e\n\u003e Instead of deduction a point when pressing the button too early, the behavior has been changed to reset the timer for the team itself.\n\u003e\n\u003e Minor changes:\n\u003e\n\u003e - Documentation is completed\n\u003e - Properly formatted code\n\u003e - Small refactoring to cleanup repeated code, as well as making some variables that do not change constant\n\n| Why this commit is considered 'good'         | Why this commit is considered 'bad'                  |\n| -------------------------------------------- | ---------------------------------------------------- |\n| Explained new behavior changes in the commit | Mention of minor changes is a bit vague in the title |\n| Minor changes is concise and specific        | Title is not in \"proper\" formatting                  |\n\n#### Examples of bad commits\n\nBad commits are easy to find and pick apart. These examples of such commits are where there are recorded bad commits.\n\nLack of detail or massive changes with something basic to describe the changes are very bad.\n\n[OakvilleDynamics/ftc-app-9328-2018-2019 @ master+884e043d48c206649db44a68512df3e32d53ab7d](https://github.com/OakvilleDynamics/ftc-app-9328-2018-2019/commit/884e043d48c206649db44a68512df3e32d53ab7d)\n\n\u003e **v0.1**\n\u003e\n\u003e Working\n\n| Why this commit is considered 'good'               | Why this commit is considered 'bad'         |\n| -------------------------------------------------- | ------------------------------------------- |\n| If versioning changes, this is at least an attempt | Commit title is vague                       |\n|                                                    | Description has nothing on what has changed |\n\n[OakvilleDynamics/FRC-Robot-Code @ main+621d4859cdc0f75acfda69f11ddf8a2606ef74a5](https://github.com/OakvilleDynamics/FRC-Robot-Code/commit/621d4859cdc0f75acfda69f11ddf8a2606ef74a5)\n\n\u003e **Cats Are Pretty Neat**\n\u003e\n\u003e Cats Are Pretty Neat + Turtles are cool!\n\n| Why this commit is considered 'good' | Why this commit is considered 'bad'   |\n| ------------------------------------ | ------------------------------------- |\n|                                      | Not at all relevant to the repository |\n\n### When to make a commit\n\nGit only takes responsibility with your changes once you have made a commit. If you forget to make a change, and something happens with your project, then work can be lost. It is highly recommended to commit as often and as early as you can **locally**. Once you have finished your changes and are ready to push, you can squash them into one single commit or push them all into the repository on GitHub.\n\nYou should commit when a change that you make still compiles, such as changing a variable name, extracted a method, or changed a conditional statement. Following this is process is committing early, and committing often.\n\n### Commit != Push\n\nA commit is just a log of changes on a repository, a push uploads your changes to GitHub or another repository. This is important as just committing those changes you've made are not automatically synced up to GitHub for others to look at and work on.\n\nIf you are clocking out for the night and you have commits that needs to be pushed, you should push them before you clock out. This is important as others can look at the work you have done, as well as if the computer you have worked on stops working, the changes you have made are not permanently lost.\n\n## Branches\n\nBranches allow you to develop features, fix bugs, or safely experiment with new ideas in a contained area of your repository. You can create branches of branches, and you can merge branches back into the main branch of the repository. Branches can be named anything, however they should be descriptive as to what is being done in the branch.\n\nYou can have an infinite amount of branches, as well as you can create \"folders\" of branches when you create a branch with the format of `[name-of-folder]/[name-of-branch]`, such as `feature/computer-vision`, `bugfix/gradlerio`, etc.\n\nIn a regular development environment, you have folders of branches that encompass lots of the changes as well as two main branches, which are considered the `main` branch or `dev` branch.\n\nThe `main` branch is the main branch, this should always be the stable branch, as this is what is considered 'production' and general uses. Commits directly to the `main` branch are frowned upon unless starting a repository and getting things all setup for others or yourself to start working.\n\nThe `dev` branch is the main development branch. This is where your new features or fixes are made, and this is considered stable but not 'production-ready'. This is due to new features and fixes can possibly have adverse effects on already existing environments. New features and fixes should be based off of this branch unless needed to be dispatched immediately. These features or fixes should be their own branches with a folder referencing the type of implementation. Once new feature is merged into the `dev` branch, you can pull request it into the `main` branch if everything is all stable and ready for a general release.\n\nFolders should be mainly comprised of overarching types of changes, such as `feature/` or `bugfix/`, as those are used to tell what the branch is supposed to be. A good example for a new feature is if someone was adding a feature to use a webcam for computer vision, a branch could be called `feature/computer-vision`, or if you were fixing a bug with power levels being too high or too low for a motor, a branch can be called `bugfix/motor-power`.\n\nA lifecycle of a branch is as follows:\n\n1. A new branch is created off of lastest `dev`\n2. Work is gone into new branch, adding or changing, or removing code as needed\n3. Once new branch is complete, merge branch into `dev`, and delete the created branch\n4. Once branch is merged into `dev` and ready for a general production release, create a pull request to `main` outlining all changes made\n5. Once the pull request is approved, it will be merged into `main`, and a commit will be made with all the changes\n6. Merge `main` back into `dev` for sanity checking\n\n### Managing branches\n\nYou should only have branches when you are fixing a bug, developing a new feature, or for experimentation. Once the task is done, you can merge it into the main branch.\n\nThe reason to have a separate branch for developing bugfixes, features, or implementing new ideas is to have the main branch as stable as possible. The main branch is what will most often be used in production environments, as well as if other features or bugfixes are needing to be developed, the main branch can be used as a good baseline for developing the feature or bugfix.\n\n### When to merge a branch\n\nMerging a branch is to be performed when the feature, bugfix, or other work that has been done is complete, stable, and is ready to deploy. This can either be done in one of two processes, either a pull request or just directly merging into the main branch.\n\n#### Pull Requests\n\nMaking a pull request is what many companies use as a check for software development. This adds a code review process to vet whether or not a branch is going to be approved into the main branch. You can offer critiques or other notes to go back and improve on, or you can approve the merge.\n\nOnce approved you can merge it into the main branch. There can be automated tools that also check for code quality, styling, or other issues.\n\nThis method is recommended for working on big multi-developer projects, as well as to get into the habit of processes from employers and general sanity checking if code will actually work.\n\nA pull request should be treated as a commit, where you can describe what changes have been made and why this should be merged if this is a new feature to be added.\n\n#### Merging directly into main\n\nMerging directly into the main branch is also an option, this is useful if you are the single developer working on a project, however if you are working on a project with multiple developers then things can get messy very quick with merge conflicts, things breaking, and other nasty issues that can creep out and ruin a merge.\n\nThis method is not recommended unless you're a single devloper working on a project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foakvilledynamics%2Fflight-rules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foakvilledynamics%2Fflight-rules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foakvilledynamics%2Fflight-rules/lists"}