↑ [[Digital Literacy]] >[!info] **[Github](https://github.com)** is >- A collaborative platform for software development. >- Maintained and hosted by Microsoft. Potential data sovereignty issues. >- FOSS alternatives available for provacy and self-hosting. E.g. [Gitlab](https://gitlab.com/users/sign_in) GitHub is an interface that allows developers to maintain public and private **[[Github#Repository|repositories]]** of code for either personal or collaborative use. It uses the [[git]] version control system. Github stores a copy of the source code for editing and discussing a project. The code is **pulled** from the source, edited, then **merged** back into the source. Once each issue with code has been resolved, the new **version** is released. It is important to note that application code is not run *from* Github. The code running an application is either stored locally on a device or on servers hosted by the developer. ## Basic Process - A user or developer opens an **issue** on Github. This is a discussion thread for reporting bugs, making feature requests, or asking questions. The project administrator sees the issue and assigns it to a collaborator. - The collaborator **creates a branch** from the project's repository and creates a separate repository in which to make changes, meanwhile other users aren't affected as the new feature takes shape. `Git` tracks the changes and keeps snapshots of the project as it develops. - Once they have drafted the code to the point of being reviewable, they open a **pull request** to share with other collaborators on their team. - Each collaborator has a copy of the project and can add code as new ideas arise over the projects course. - When the team signs off on the changes and agrees to ship - the lead collaborator **merges** the pull request into the project. Making the new feature available to anyone with access to the code. ## The Repository ^990f30 A repository is the primary container for all information related to a project. - **Code View** is the main code console for the projects completion. - Any type of code can be written in the `code` space. Git will read and tag what type of code it is in the repository HUD. - `main` is the main code file. This view is also called the **root**. - `README.md` is an encouraged file to communicate best practices, definitions, and methodology. - The `CONTRIBUTING.md` is used to describe the process for contributing to the repository. A link to the `CONTRIBUTING.md` file is shown anytime someone creates a new issue or pull request. - The `ISSUE_TEMPLATE.md` is another file used to pre-populate the body of an issue. For example, if you always need the same types of information for bug reports, include it in the issue template, and every new issue will be opened with your recommended starter text. - `/docs` is a **directory** used for documenting the project. - This is also the directory from which [[GitHub pages]] will publish content ### The Github flow ![[githubFlow.png|800|center]] #### Issues - A user or contributer identifies a bug or makes a feature request per the guidelines in the `README.md` file. - A moderator reviews the issue and assigns it to a contributor. - The contributor opens the relevant file to be edited and initiates a **pull request**. - Issues are a good way of tracking to-do lists for developing completed projects. #### Pull Request - This is essentially asking the team or bot to *pull* a copy of the code from its directory and create a new branch to be edited. - Typically a pull request is created in response to an issue. - Its a work-in-progress draft of code that allows other contributors to comment and refine. - It also tracks changes by highlighting new code green and old code red. #### Branching - A **branch** is a parallel version of a repository. It is contained within the repository, but does not affect the main branch. This allows the code to be manipulated over the course of editing while the main code remains “live” - Branches allow for improvements to be made while the current version remains active - The best way to keep branches organized with a team is to keep them **concise and short-lived**. A single branch should represent a single new feature or bug fix. This reduces confusion among contributors where branches are only active for a few days before they’re [merged](https://help.github.com/articles/github-glossary/#merge) into the `main` branch. #### Committing - Once the code has been revised to address the initial issue it is ready to be committed. - A **commit** is the same as saving but it is *recording the history of the change*, not overwriting the file. - `git` keeps a complete history of the project and is able to restore it to any point in the line of commits. - The "Commit new file" section is below the code block in the pull request. In the first field, type a commit message. This message should briefly tell contributors about the changes being introduced ##### Commit Best Practices: - Don’t end commit messages with a period. - Keep messages to 50 characters or less. Extra details can be added in the extended description window just below the subject line. - Use active voice/present tense - The commit expresses an intent to introduce a change. - Commits can be made directly to the main branch or to a separate branch by creating a *pull request*. - Small, typographical edits can be made directly to the existing branch. - Adding features or fixing bugs should be commited to a new branch via pull request. #### Merging **Merging** applies the changes from one branch to another, usually between the patch and main branches. This can occur from same repository or a fork. For individual projects this is fairly linear but may require additional commits in collaborative projects. Once a request to merge is made, the code is reviewed and additional changes can be requested. Merging is the last step in the pull request process. ## Links --- - Concise [introduction](https://anyone-can-cook.github.io/rclass2/lectures/git_and_github/git_and_github.html) to Github and it's utitilty - The `git` [user manual](https://anyone-can-cook.github.io/rclass2/lectures/git_and_github/git_and_github.html) - Github [documentation](https://docs.github.com/en/get-started/start-your-journey/hello-world) - Simple `git` [tutorial](https://www.w3schools.com/git/default.asp?remote=github) from w3schools. - [Intro to Github](https://github.com/skills/introduction-to-github) tutorial repository.