Getting started with GitHub and Codewind

New to GitHub and contributing to Codewind? No worries! Get started here to start contributing to Eclipse repos, create a pull request, and more.

Setting up your Eclipse account

Create an Eclipse account. Verify your account after you receive the verification email.
Sign the Eclipse Contributor Agreement (ECA).
Associate your Eclipse profile with your GitHub ID. For more information on how to set up your Eclipse account, see the Codewind GitHub Workflows wiki.

Select your editor.
- A. Use Eclipse, VS Code, the command line, or a combination of these tools to create a pull request. Unless you're an Eclipse committer, your commit needs to include a signoff statement, which you can't add with GitHub Desktop or the GitHub web browser.
- B. These instructions show how to use the command line to work with GitHub and VS Code to edit a file.
If you don't already have access to Git commands with your Terminal, set it up by completing the instructions in Creating a personal access token for the command line.
Clone the repo that contains the files you want to edit.
- A. Go to the Code tab of the repo and click Clone or download.
- B. Copy the text in the Clone with SSH text box.
  - If you currently don't have any SSH keys on your machine and associated with your GitHub account, go to the Adding an SSH key section.
- C. Go back to your command line and go to the folder in which you want to clone the repo.
- D. Enter the command git clone <name of repo>. In place of <name of repo>, paste the text from the Clone with SSH text box.
Create a fork.
- A. Go to the repo that you want to create a copy of. Click Fork.
- B. When prompted to choose a location for the fork, click your account.

Follow the steps from this link: Generating a New SSH Key and Adding it to SSH Agent.
Follow these steps to modify your ~/.ssh/config file to automatically load keys:
- A. Open your command line.
- B. Enter the vi ~/.ssh/config command.
- C. Enter the following commands:
```
Host*
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_rsa
```
- D. Enter the ssh-add -K ~/.ssh/id_rsa command.
- E. Enter the cat ~/.ssh/id_rsa.pub command. A link appears.
- F. Go to the profile on your GitHub account.
- G. Select settings.
- H. Select SSH and GPG keys from the Personal settings table.
- I. Select New SSH Key.
- J. Name your SSH Key. Example: your name-Mac
- K. Copy the link from your command line and paste it in the SSH Key box. You now have the SSH Key to use.

You now have three repositories for the same content:
- Remote (master): The main repo that exists on the web as part of the Eclipse project.
- Local: The cloned repo that resides on your local machine.
- Your fork.
Now, set up a triangle workflow to keep these three repositories in sync with each other.

From the command line, cd into the repo folder.
Rename your origin to upstream with git remote rename origin upstream.
- The command breaks down like this: git remote rename <current name of repo> <new name of repo>.
Add your fork:
- A. Go to your fork on the GitHub web browser and click Clone or download.
- B. Copy the text in the Clone with SSH text box.
- C. Go back to the command line and enter git remote add myfork [email protected]:<user>/<project>.git, replacing [email protected]:<user>/<project>.gitwith the content that you copied from the Clone with SSH text box.
  - Example: git remote add myfork [email protected]:samplename/codewind-docs.git
Check the names of your fork and your cloned repo by entering the git remote -v command.
- Your fork is myfork.
- The cloned repo that exists on your local machine is upstream.
Enter the following commands to connect the three copies of the repo: git config remote.pushdefault myfork git config push.default current

From the command line, use the cd command to go to the repository of the file you want to edit.
Go to your master branch. If you are working on multiple branches at the same time, make sure you go back to the master branch between creating new branches. If you do not return to master, the changes that you made on one branch can get pulled into the new branch.
Update your branch with the git fetch and git pull commands.
Create a new branch on which to make your edits.
- A. Enter git branch to view your existing branches.
- B. To create a new branch, enter git branch <name of new branch>.
- C. Make the name of the branch descriptive, such as your GitHub ID, the issue number that the update applies to, and brief description: samplename_1122_addnews.
Go to the new branch with the git checkout <name of branch> command.
Open the file you want to edit, make your changes, and save them.

To view the files that you edited locally, enter git status.
To add the files to be committed, enter git add <file path>/<name of file>. If you are deleting a file, enter git rm <file path/<name of file>.
To commit the files, enter git commit -s -m "<information about changes>".
- Note: The -sincludes a sign-off statement with your commit. The sign-off statement is essential for Eclipse project commits if you are not a committer.
To push the files to GitHub, enter git push or git push --set-upstream myfork <branchname>.
Now, on the web, go to the repository on GitHub where you pushed your changes.
- A. Click Compare & pull request. A new page opens where you can create your pull request.
- B. On the pull request page, add a description and a link to the issue that the pull request applies to.
- C. Click Create pull request. The pull request is created. Make sure that the All checks have passed message appears.

To integrate the changes from the pull request, they need to be merged to the master branch.

You might need to work on more than one branch. For example, you might start Issue 1, create a branch for its changes, and then start working on a separate branch with separate changes for Issue 2.
If you are on Issue1_branch for your Issue 1 changes, you must go back to the master branch before you create your Issue2_branch for Issue 2 changes. If you stay on the Issue1_branch, you will create your Issue2_branch off of the branch for Issue 1, and all of your changes for Issue 1 will be included with the Issue2_branch.
Remember to create all of your new branches off of a freshly updated master branch.

After your branch is merged to the master branch, you no longer need the branch.

Delete the branch in the GitHub web browser.
Go to the Terminal and remove the branch with git branch -D <name of branch to remove>.