ashwin-pc/contributing your first PR.md

## contributing your first PR.md

      
    Raw
  

              contributing your first PR.md
            
          
    Contributing your first PR

1. Installing Git


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


2. Configuring Git

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 "youremail@example.com"


2.1. Authentication

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.
3. Forking a Repository


Navigate to https://github.com/opensearch-project/project-website
Click the Fork button at the top right corner.

4. Cloning the Forked Repo & Setting Upstream

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)

5a. Setup the Project (Optional)

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.


5b. Creating a Branch

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


6. Making Changes & Committing with Signoffs

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"


7. Opening a PR (Pull Request)


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.

8. Reviewing a PR


Navigate to the 'Pull Requests' section of the repository.
Choose a PR to review.
Leave comments, suggestions, or approve the PR.

9. Keeping Fork in Sync

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
Relationship between Git and 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


My git workflow


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

Useful resources

Here's a list of reading materials and resources:
1. Useful links


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.

2. Official Git Documentation


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.

3. GitHub Guides


Hello World: A beginner's guide to making the first contribution on GitHub.
GitHub Flow: The workflow recommended by GitHub for project contribution.

4. Other Useful Resources


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.

5. VS Code extentions


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.

Git & GitHub Words Explained with Context


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.