- For Windows: Git for Windows
- For Mac: Use Homebrew (
brew install git
) or download from Git website - For Linux:
sudo apt-get update sudo apt-get install git
- Verification: Check installation with the command:
git --version
This is necessary for signing your commits with your name and email address. You can skip this step if you have already configured Git on your machine.
- Set your user name:
git config --global user.name "Your Name"
- Set your email address:
git config --global user.email "[email protected]"
With the recent changes to githubs access policy you can nolonger use your password to authenticate your git requests. You can instead use Github's personal access tokens. To get your access token, go to https://github.com/settings/tokens and generate a new token. The default token permissiions should be sufficient. Then when prompted, use the generated token as the password and your github ID as the username to authenticate any git requests to your repository.
- Navigate to https://github.com/opensearch-project/project-website
- Click the
Fork
button at the top right corner.
The flow I prefer here is to have a single fork of the repository as origin and the original repository as upstream. This way, you can keep your fork in sync with the original repository and also push your changes to your fork.
- Clone your forked repository to your local machine:
git clone https://github.com/YOUR_USERNAME/REPO_NAME.git
- Set the original repository as upstream:
git remote add upstream https://github.com/ORIGINAL_OWNER/REPO_NAME.git
- Verify the remotes:
git remote -v
You should see somethign like this:
origin https://github.com/ashwin-pc/project-website.git (fetch)
origin https://github.com/ashwin-pc/project-website.git (push)
upstream https://github.com/opensearch-project/project-website.git (fetch)
upstream https://github.com/opensearch-project/project-website.git (push)
Now for the pruposes of this workshop, this step is optional because installing ruby and bundler can take some time depending on your particular configuration of OS and system. If you want to follow along with the workshop, you can skip this step and instead follow the instructions in the README.md file of the project-website repository later to test your changes.
-
Navigate to the project directory:
cd REPO_NAME
-
Follow the instructions in the README.md file to setup the project. This may sometime also be in the Developer Guide file instead of the README.md file.
It is good practice to create a new branch for each feature or bug fix you are working on. This way, you can keep your main branch clean and also have a clear history of your changes.
- Navigate to your local repository directory.
- Create and switch to a new branch:
git checkout -b feat/profile
Here the change we are making is to create a new profile page for yourself. To do so navigate to the _authors
folder and create a new file with your name. You can copy the contents of the _authors/osci_2023/_template.markdown
file and make the necessary changes.
- Make your changes in the repository.
- Add the changes:
git add .
- Verify the changes, you should only see the files you want to commit:
git status
- Commit the changes with a signoff:
git commit -s -m "Your commit message here"
- Push the branch to your fork:
git push origin branch-name
- Navigate to the original repository on GitHub.
- Click on
New Pull Request
and select your branch.
- Navigate to the 'Pull Requests' section of the repository.
- Choose a PR to review.
- Leave comments, suggestions, or approve the PR.
The easiest way to do this is to navigate to your fork of the repo and sync the changes there or using the github CLI and then pull the changes from your fork down to your local, both of which are covered here: Syncing a fork. Yuocan however do this using just git too. To do so using git:
- Fetch updates from the original repo:
git fetch upstream
- Merge updates to your local repository:
git checkout main git merge upstream/main
- Push the change to your fork
git push origin
another option is to use the github
graph TD
A[Local Repo] -->|git push| B["Origin (Your Fork on GitHub)"]
B -->|git pull| A
B -->|raise PR's| C["Upstream (Original Repo)"]
C -->|github sync| B
- Sync fork before working on any change
- Pull the latest version of the code from
main
- Create a new branch for the change I want to make
- Make changes and stage them
- Verify that the changes are accurate
- Commit the changes with --signoff
- Push the branch with my changes to my fork
- Raise a PR to the upstream repo's
main
branch from my branch in the forked repo. - Add screenshots and a useful description of my change to the PR
- Depending on the repo, I might also need to make a second commit to the PR to add a changelog entry. I make the change to the
Changelog.md
file and commit the changes using steps 4-7
Here's a list of reading materials and resources:
- Learn Git Branching: An interactive website to learn Git branching, among other features.
- Mastering Markdown: Markdown is used in READMEs, comments, and other places on GitHub. This guide helps in getting started with it.
- Git Basics: This section from the official Git documentation covers the basics of getting and creating repositories.
- Git Branching: A thorough look into branching in Git.
- Pro Git: Written by Scott Chacon and Ben Straub, this is a comprehensive source on Git. It's available online for free.
- Hello World: A beginner's guide to making the first contribution on GitHub.
- GitHub Flow: The workflow recommended by GitHub for project contribution.
- GitHub Git Cheat Sheet: A quick reference guide to common Git commands.
- Oh Shit, Git!: A humorous take on "how-to" guides for when things go wrong in Git.
- GitLens — Git supercharged: Provides powerful Git capabilities, such as inline Git blame annotations, code lens with a recent change info, and much more.
- Git Graph: View a Git Graph of your repository, and easily perform Git actions from the graph.
-
Repository (Repo): Think of it like a special folder for your project. Whenever you start a new project or wish to join an existing one, you'd interact with a repo.
-
Commit: Saving changes is like taking a snapshot of your project at a particular time. When you've made a change and want to keep a record, you'll make a commit.
-
Branch: A version of your project that allows you to try new things. Before adding a new feature or fixing a bug, you might create a branch. The primary branch you start with is called the Main Branch.
-
Clone: Making a personal copy of a project to your computer. If you come across an interesting project online and want to work on it, you'd clone it.
-
Fork: It's like borrowing someone's project to make your own version. If you wish to suggest changes to someone else's project, you'd first create a fork of it. Your personal online copy of this borrowed project is called the Origin.
-
Push: Uploading your project updates online. After you've made changes on your computer, you'll push them so others can see.
-
Remote: This refers to the online version of your project. When you save or back up your project online, you're using a remote. The initial project you might have borrowed and its updates are known as the Upstream.
-
Pull: Downloading the latest updates from online. If you wish to see the most recent changes others have made, you'd pull them.
-
Pull Request (PR): It's like sending a message saying you've made some changes and asking if they can be added to the main project.
-
Merge: Combining changes from different versions. Once everyone agrees on the changes, they're merged, typically into the Master (or Main) Branch.
-
Blame: Determining who made a particular change. If you're curious about who edited a piece of code, you'd use blame.
-
Fetch: Like previewing the latest updates without actually applying them. If you're curious about what's new but aren't ready to update your version, you'd fetch.
-
Stash: Temporarily setting aside changes. If you're in the middle of something and need to switch tasks, you can stash your current work.
-
HEAD: Refers to the most recent change you've made. If you're looking back at your last update or considering undoing it, you're dealing with the HEAD.
-
Checkout: Picking which version of your project to see or work on. If you're interested in exploring different branches or revisiting an old version, you'd use checkout.
-
Conflict: A situation when two changes clash, causing confusion. If two people edit the same part of a file and the system gets confused, you'd have to resolve this conflict.
-
Repository Owner (Repo Owner): The main person responsible for a project. If you have questions or need special permissions, you might contact the repo owner.
Got it! Many thanks @ashwin-pc