Contributing to ESE via. Git

This guide only applies to those who have access to the TJADB Gitea. Those who are only interesting in downloading should read here instead. This tutorial may look intimidating, but will become second nature over time.

If you want to contribute, but don't have a Gitea account, please request one from Pidgey on Discord.

1. Download Git

Download and install Git here.

2. Fork ESE

Cloning the original ESE repository will not work for this setup, as you will not have permission to edit the original repository itself. Instead, you must create your own fork, so that you can propose changes that the admins will accept.

3. Setup using Git GUI

Run "Git GUI" by searching for the application or right-clicking inside any file explorer window to open it. In this window, click on "Clone Existing Repository".

"Source Location" is the repository that you will be downloading from. Go back to your forked repository & look for the .git URL towards the top-right. Copy this link & paste it into the Source Location bar. Do NOT copy your browser URL, this will not work! A .git link is required.

"Target Directory" is where the repository will be installed on your computer. Browse anywhere on your computer & pick a folder where you want to install the repository (pick a location where you'll easily find it!). After that, add ESE to the end of your Target Directory. This will create a new folder inside that folder titled "ESE" & download all the files from your repository. Do NOT create a new folder called ESE before cloning your repository. Git GUI will return an error if the folder already exists, even if the folder contains nothing!

If you've done everything correctly & successfully downloaded your repository, you should now see this window :

Updating your Repository

As ESE is continuously updated, your fork of ESE will likely fall behind. To update your repository, run Remote -> Fetch From -> upstream. This will pick up any changes that've happened to the original repository.

Sending updates to ESE

Before submitting changes to ESE, it's recommended to create a new branch. If you continue using your main branch to submit changes, you will continuously resubmit previous changes that have already been accepted, and eventually run into merge conflicts in the future.

1. Create a new Branch

Go to Branch -> Create.... Name this branch whatever you want and make sure the Starting Revision is set to Tracking Branch -> upstream/master, and then click Create. This will create a new branch, and also download the latest changes to ESE to ensure that you're up-to-date.

From here, you can create/update any files to submit.

Switching Branches

If you've updated your main branch instead of your new branch, you may've noticed that your updated files went missing when switching to a different branch. Your updated files are still saved, and you can go back & recover them at any time by going to Branch -> Checkout... and selecting the branch you want to switch back to. However, unstaged files will follow you into other branches (read below).

2. Commit Changes

When you've added/updated your files, they will appear in your Unstaged Changes tab. If you do not see these, go to Commit -> Rescan or press F5. If all of these changes look correct to you, go to Commit -> Stage Changed Files to Commit to prepare all changed files for commiting. If there are some files that you are not ready to commit yet, you can hand-pick which files you want to commit by holding Shift and clicking on each file you want to commit, and then going to Commit -> Stage to Commit.

All commits require you to write a commit message, stating what changes you've made. Your first line should be a simple sentence stating your change (required), your second line should be blank (optional), and your remaining lines should describe your changes in more details (optional).

3. Push & Pull Request

When all of your commits are finished, click on the "Push" button to upload your changes.

Pushing allows you to send your commits back to your repository on the TJADB Gitea. You can push your commits anytime you want. Once pushed, you will be able to access and view your commits online. When you've verified that you've made & uploaded all the changes you want, you can now start a Pull Request.

Pull Requests are requests sent to the repository you forked from, asking the owners of the original repository you forked from to update using the commits you made. Return to the ESE Repository & go the Pull Requests page, and at the right, click on "New Pull Request". Click on pull from: ... & point it to your repository's branch, containing all the new changes you want to submit. After that, click "New Pull Request" to begin the process.

Once you've sent your Pull Request, the admins in charge of the ESE repository will review your changes & accept them if they look good. You may be asked to update your files if they don't look correct. If so, commit & push your new changes; You can continue to send changes while the Pull Request is still open.