-
Notifications
You must be signed in to change notification settings - Fork 18
Home
This wiki page has the objective to establish some ground rules on what is the best way to contribute to the Solutions Architect Open-Source Community and help you understand better how Git/GitHub works so you can safely make your contribution.
In this GitHub 101, we will explain the features of Git/GitHub and explore major components that you need to know to make contributions to this project, and also use projects that others have shared here.
Here are the topics that we are going to discuss:
- What is Git/GitHub
- Repository
- Forks
- Branch
- Commit and Push
- Issue
- Pull request
- GitHub Actions
- Helpful Tools (optional)
Git is a free and open-source distributed version control software designed to handle everything from small to very large projects with speed and efficiency.
GitHub is a code hosting platform for version control and collaboration based on Git software. It lets you and others work together on projects from anywhere.
Learning all available Git commands at once can be a daunting task. You can use Git Cheat Sheets for a quick reference to frequently used commands. The "Using Git" cheat sheet is available in several languages.
In addition, take a look at our Git and GitHub learning resources page that links to guides, videos and more.
A repository is the most basic element of GitHub. They're easiest to imagine as a project's folder. A repository contains all of the project files (including documentation), and stores each file's revision history. Repositories can have multiple collaborators and can be either public or private.
A fork is a copy of a repository that you manage (under your GitHub account). Forks let you make changes to a project without affecting the original repository. You can fetch updates from or submit changes to the original repository with pull requests. You can fork a repository to your personal account or any organization where you have repository creation permissions.
Forking a repository is similar to copying a repository, with two major differences:
-
You can use a pull request to suggest changes from your user-owned fork to the original repository in its GitHub instance, also known as the upstream repository.
-
You can bring changes from the upstream repository to your local fork by synchronizing your fork with the upstream repository.
In open source projects, forks are often used to iterate on ideas or changes before they are offered back to the upstream repository. When you make changes in your user-owned fork and open a pull request that compares your work to the upstream repository, you can give anyone with push access to the upstream repository permission to push changes to your pull request branch (including deleting the branch). This speeds up collaboration by allowing repository maintainers the ability to make commits or run tests locally to your pull request branch from a user-owned fork before merging. You cannot give push permissions to a fork owned by an organization.
Deleting a fork will not delete the original upstream repository. You can make any changes you want to your fork—add collaborators, rename files, generate GitHub Pages—with no effect on the original. You cannot restore a deleted forked repository.
To make your contribution, please follow the Contibution link in the README.
Branches allow you to develop features, fix bugs, or safely experiment with new ideas in a contained area of your repository.
You always create a branch from an existing branch. Typically, you might create a new branch from the default branch of your repository. You can then work on this new branch in isolation from changes that other people are making to the repository. A branch you create to build a feature is commonly referred to as a feature branch or topic branch. For more information, see "Creating and deleting branches within your repository."
There is no naming convention for branches, although will be helpful for everyone if you choose a "meaningful" name for your branch, take for example the Group Mover Project, you can follow this example and use the name of the project as the branch name or in case you want to update a current project you can use words like "update" or "feature-update" to better identify your intentions on that branch.
A Commit, or "revision", is an individual change to a file (or set of files). When you make a commit to save your work, Git creates a unique ID (a.k.a. the "SHA" or "hash") that allows you to keep record of the specific changes committed along with who made them and when. Commits usually contain a commit message which is a brief description of what changes were made.
A Push means to send your committed changes to a remote repository on GitHub.com. For instance, if you change something locally, you can push those changes so that others may access them.
An Issue is essentially a way to track ideas, feedback, tasks, or bugs in your repository. Issues can be created in a variety of ways, so you can choose the most convenient method for your workflow. For example, you can create an issue from a repository, an item in a task list, a note in a project, a specific line of code, or a URL query. Another great way to use issues besides to report bugs is to link with a Pull Request(A possible coming fix for that bug), add labels to categorize and attach that issue to a project or to a Milestone to track progress on groups of issues.
To create an issue in this repository you can do it here. The issues in this repository are standardized by templates, and you should choose between the following templates: Bug Report, Feature Request or New Solution Request
Pull Requests allow you to tell others about changes you've pushed to a branch in a repository on GitHub. Once a "pull request" is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.
In this repository, Pull Requests are used as the main workflow to make your contributions. To add any code to the main branch, a Pull Request will be necessary, not having any other method for your code to reach the main branch.
As a standard, we do have a Pull Request Template that must be used to make your code reach the main branch at some point.
In the process to make your PR, you must select the Reviewers and the Assignees and we highly recommend attaching labels to the Pull Request, so it's easy afterward for you and others to find/identify this. Also as a best practice and when possible, you can attach open/close Issues or even Projects/Milestones to the PR.
After opening a PR, make sure that you have enabled the notifications in case any reviewer request any modifications and additional commits to the code pushed.
GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. The idea of using this platform is to help automate boring tasks, such as building and testing every pull request to your repository or merging pull requests to production.
You can use any “pre-build” actions directly from GitHub Marketplace or build your own from scratch. For each action, you can run your workflows on Linux, Windows, and macOS virtual machines provided by GitHub. These actions will help you to automate your workflows and it will trigger when an event occurs in your repository, for instance, to automatically create a new release package every time that code is merged to the main branch.
Here is a very simple example of using actions to setup a nodejs environment:
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node: [ '12', '14', '16' ]
name: Node ${{ matrix.node }} sample
steps:
- uses: actions/checkout@v3
- name: Setup node
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node }}
- run: npm install
- run: npm test
By using this action, a file under .github/workflows/ will be created in your repository (With a default name of main.yml, you can change it to anything you want). You can edit this file to add more actions to it or create a different file to set up a new workflow.
For more information on how to configure your automation, refer to the GitHub Actions Documentation
During your journey to make your contribution and be part of our beloved open-source community ❤️, some existing tools might help you along the way, here are some of these tools that you might want to use:
-
Visual Studio Code -> Visual Studio Code, also commonly referred to as VS Code, is a source-code editor made by Microsoft for Windows, Linux, and macOS. Features include support for debugging, syntax highlighting, intelligent code completion, snippets, code refactoring, and embedded Git.
-
GitHub CLI -> The GitHub CLI or
ghis the GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with git and your code. -
GitHub Desktop -> GitHub Desktop extend the features of GitHub, is a tool that allows you to interact with GitHub from the desktop. You can work easier without having to depend on your browser.
-
Git CLI -> Git is a set of command-line utility programs that are designed to execute on a Unix-style command-line environment. Modern operating systems like Linux and macOS both include built-in Unix command line terminals.
https://docs.github.com/en
https://guides.github.com
https://cli.github.com
https://code.visualstudio.com
https://desktop.github.com
https://lab.github.com/githubtraining/introduction-to-github
https://git-scm.com