Skip to content

How to: submit a PR to a KSP RO project 101

Stonesmile edited this page Jan 6, 2023 · 4 revisions

This guide assumes no prior knowledge about GitHub, but does assume that you know what changes you want to contribute to a project.

Basics

First off; if you have not already, you need to create a GitHub account.

To be able to submit changes to a project, you need to go to the github page of the project you want to contribute to and click fork in the top right corner. This creates a Separate copy of the project that you can change without it affecting anything in the original project. This is the version of the project that we will use for the rest of this tutorial, and not the main project. Do note that this only needs to be done once for each project and the next time you want to contribute something to the same project you use the same fork that you just created.

Add your change

With your new copy of the project, you need to add your change. This can be done in several ways, some of which are covered here.

Web-VSCode

VSCode

Visual Studio Code for the Web

One of the easiest ways for making a simple change is the web version of Visual Studio Code (VSCode). Web-VSCode is accessed by pressing . while having your fork of the project open in your web browser. (Visual Studio Code on Desktop is very useful for larger changes too, covered below)

It's easiest to keep track of your changes if you make them to a new branch instead of to master. You can make a new branch in web-VSCode by clicking the name of the current branch in the bottom left of the window and then Create New Branch... in the dialog that pops up. The name of the new branch doesn't really matter, but it can be useful for keeping track of different branches if the name reflects what changes are being made, or alternatively just patch-1 if nothing better comes to mind.

image

With a new branch set up in web-VSCode, you need to make your changes to the files.

After making your changes in web-VSCode, the changes need to actually be added to the project. This is done under the Source Control tab in VSCode.

image

Here you have all of your changes under the "Changes" header. Clicking on a file here will bring up a split window where you can compare the file before and after the change. Hovering over a file in this list will reveal 3 icons, "Open File", "Discard Changes" and "Stage Changes". Clicking "Stage Changes" will move the change from the "Changes" header to a new "Staged Changes" header. Only changes that are moved to this "staged" section will be included in the actual project when you commit them.

After staging your changes, add a commit message shortly describing what your change does, and click "Commit and Push". This adds the change to your personal fork of the project.

image

Now you need to create a Pull Request to request the change to be merged into the original repository. This is covered further down after the other ways to add changes has been covered.

Using Visual Studio Code on your own PC

This section relies on information written in the section about using the web-version of VSCode from above. Please read that section too, if you are not already familiar with web-VSCode.

Install VSCode

To use VSCode on your local computer, you need to download it, either from the website or Microsoft Store.

Setting up Git for use with VSCode

I am not sure if this section is needed. If it is, please edit this section with your experience!

Cloning your repository to your PC

After installing VSCode, we need to get a linked copy of your forked repository on your PC. This is done by opening VSCode with no folder or project open and going to the Source Control tab. If you have a folder open in VSCode and the source control tab does not look like the left picture below, you can instead open a new window through the menu bar by using File > New Window (3rd item).

Under the Source Control tab we want to use the option Clone Repository and in the prompt that shows up we want to paste the link to the fork of the repository, found on the github page for your fork under the green box Code, and clicking the copy icon next to the link shown, or directly copying the link like any other text.

After submitting the link to the fork in the prompt, VSCode will ask for a location to place the files in. Do note that the location you choose is where the main folder will be placed inside, and not where all of the content is directly placed. (Some/Where/On/Your/PC/SelectedFolder/projectFolder is the structure that will be created)

With this done, you can make your change to the files. Remember that you can see what changes has been made under the Version Control tab in VSCode while working on your change.

After making your change, the process of actually adding it to your fork is the same as when using Web-VSCode (See above). The only extra step is that when a "commit" is made, it is not automatically pushed to GitHub. This is instead done manually by clicking Sync Changes in the empty source control tab (Shown below). If this tab is not empty due to some additional changes being made that was not included in the commit, then clicking the button next to the branch name at the bottom left of the VSCode window does the same and pushes the change to GitHub.

image

Now you need to create a Pull Request to request the change to be merged into the original repository.

Making a Pull Request

Go to your fork of the repository on GitHub. GitHub should have detected the new change and show a box asking you if you want to create a Pull Request. Alternatively, if this isn't showing, using the Contribute button while looking at your new branch, here marked with a red line, does the same thing.

image

Click the "Compare & pull request" button. Here you can change the title of the PR or add comments. If you want to contribute to a branch other than the master branch, you will need to change the "base:" field. If you scroll down, you will be able to see all the changes that will be included in this PR. Make sure that they are what you expect!

Clone this wiki locally