So, you're a maintainer and you have no idea how to do your job? You've come to the right place, here you'll learn how to not fuck everything up beyond repair like you already did with a few PRs, most likely.
- 1 Maintainer's duties
- 1.1 Managing normal PRs
- 1.2 Dealing with mirrors
- 1.2.1 How do I recognize a mirror from a normal PR?
- 1.2.2 What are the basic checks I need to run before merging a mirror?
- 1.2.3 Something went wrong!
A maintainer is supposed to:
- Manage normal PRs;
- Check mirrors' integrity and merge them where possible;
- Help other coders in need.
It may sound hard, but it's pretty much a repetitive process, and you don't even need full dream maker knowledge to keep the code base up and running.
Managing normal PRs
There are two types of "normal" PRs (as in, any PR that is not a mirror) you'll be dealing with:
Whereas the same "techniques" apply when dealing with them, there's a small difference: Pull requests only require a codecheck to be merged, whereas features require headmin's approval. The latter means that 2 headmins must write their +1 on said PR, although GMs also count in, with their vote counting as half a head's. Thus four GMs are enough to merge a PR, or 1 HA and 2 GMs. Code checking and merging are different. You can codecheck a PR by approving it, like in this screenshot.
- You can comment a PR to discuss certain parts of it without explicitly giving your approval.
- You can request changes to a PR if you find certain parts of the code being broken or not conforming to our code standards. You'll have to actually write a review, you can't just request changes without explaining what needs to be changed.
- You can approve a PR if you are sure all the code works as intended. The moment you do it, the PR responsibility falls on you, not on whoever merges it. If it's broken, you will be whined at.
If the PR is good to go, has enough headmin's approval where needed, it has a codecheck (can be yours or any other maintainer's) and all the checks (travis, mapbot and anything else that may be added in future) pass, then it may be merged. You just have to press "Squash and merge" at the bottom of the PR, then confirm it. You can edit the commit message the PR will be merged with, in case you have a better one. That's all for managing normal PRs. At the end of the day, what matters here is the code check, since that is your duty, and that requires code knowledge.
Dealing with mirrors
This is what you'll do daily as a Hippiestation maintainer. Most of the time, mirrors just need to be approved and merged, but there will be times where they will break and you'll have to fix them.
How do I recognize a mirror from a normal PR?
Easy. It has a [MIRROR] at the start of its title. For example, []. It also has the label "Upstream PR merged" given by the pr mirror bot at creation's time.
What are the basic checks I need to run before merging a mirror?
- Do all the checks pass? If yes, go to 2.
- Are the number of changes equal to the mirrored PR's ones? To understand this better, view the screenshot, then go next.
- Was it NOT reverted by the upstream recently? If it was reverted, it's pointless to merge it then merge the revert. Just close both.
If the mirror passed all those steps, then it's safe to merge it in the same way you merge normal PRs. You squash and merge, confirm it, but there is also another thing you need to do: Delete the mirror branch. You can do this after merging, a new button exactly for the task will appear. Just press it. That way the repository won't end up with 100 useless branches.
Something went wrong!
Well fuck, this is the worst part of dealing with mirrors. It can be as easy as restarting travis' job, or you may actually have to edit the mirror in local due to some core changes that must be applied to our code. Before a quick rundown on what sort of cases you may have to deal with, from the easiest to the hardest, the most important thing is to know how to actually edit a mirror. You can either:
- Web-edit it
You can do so by going into the PR's changed files and clicking the little pencil on the top right of the file you want to edit. This will open an online, quick editor, good for minor changes. Huge files like maps won't even open, you'll have to:
- Locally edit it
Which you can do with some commands (This is for git bash, if you use any other client, I can't really help you here but we can find how to on discord):
- git pull upstream pull/PRID/head:YOURBRANCHNAME
Change the PRID with the ID of the PR, usually the four numbers after the # in the PR; Change YOURBRANCHNAME with any name you want to use for your branch.
- git checkout YOURBRANCHNAME
to move to your newly made branch.
- Do your local edits
- git add .
- git commit -m "Whatever message you want for the commit"
- git push upstream YOURBRANCHNAME:BRANCHOFTHEMIRROR
BRANCHOFTHEMIRROR is the branch the mirrored PR code is in, which you can view from the top of the PR. Usually it should be like "upstream-merge-(some numbers)".
Now, a list of frequent mirror fuck ups and how to solve them
Travis fucking up (easy)
If travis whines about something, click on the "Details" hyperlink next to the failing travis check. You'll be sent to the PR checks that travis ran and had problems with. In the case of an easy fuckup, it should look similar to this: As you can see, two checks passed, but the middle one failed for some reasons. Click on it and the "job" log, aka the checks that travis ran, will display. You'll need to analyze it and see where it fucked up, but do not worry, it should be relatively easy. In the case that it complains about either rust-g or some sql stuff, then you're lucky. You will only have to do a few things.
- While in the same window, press "Restart job" located top right of the same window containing the job log (not the main one with the 3 checks, that'll restart ALL of them and it will take a LOT more time. Just restart the failing check). If the error happens again, you'll have to:
- Delete the cache. You can do this by going on More options located just above the restart job button, then "Caches". You will see a lot of caches, with a little bin on the far right to delete them. Delete the master one and the upstream-merge-whatever that is supposed to be the branch of the mirror PR you're fixing. After you did this, you can go back and press "Restart job" again, it must pass this time, unless you're very unlucky. In this case it's best to contact me directly (Carbonhell), you may either be unlucky or something may have gone horribly wrong.
The most hated part of dealing with mirrors (and sometimes PRs in general), merge conflicts can happen when the upstream and the origin files are different, thus the upstream changes cannot be applied directly on the origin's file (upstream being /tg/ for us, origin being our repo). When this happens, our bot will apply some special tags to the files conflicting:
>>>>>>> (some SHA related stuff) (commit message)
As a maintainer, part of your job is to resolve those conflicts. There will usually be some code between <<<<<< HEAD and ========, and between ===== and >>>>>>. The former contains code currently in our repository, whereas the latter has the code the upstream is trying to merge in our files but cannot. You cannot just remove those tags, otherwise you will leave double the amount of code which will cause errors.
- If our part of code has nothing done by us (which is usually tagged with a // hippie comment), you're safe to just delete all the former code, and leave only the upstream's.
- If there's something made by us, then you need to be careful, analyze the code and try to leave our //hippie stuff inside while also updating tg's code.
Once done, you're safe to remove the three merge conflict indicators, since you also removed the double code part. If travis passes, congrats, you (most likely) did it!
/tg/ PR not mirrored
It can happen that a tg PR isn't mirrored, due to the PR mirrorer bot having issues. In this case, you will have to do it manually. Don't worry though, it is pretty easy:
- Checkout to your master and update it. It must be in sync with the repo, or else you will fuck up.
- Create a new branch and checkout to it.
- Go to the PR that you need to mirror, for example https://github.com/tgstation/tgstation/pull/39075
- Click on the merge commit, like in the example:
- Your url will now look like this: https://github.com/tgstation/tgstation/commit/90a1b8c3638c09cf3d696facc228225d369ba6e4
- The merge commit SHA which you need is after commit/ and you need to copy it.
- Back in git bash, execute: 'git cherry-pick "MERGESHA"' with MERGESHA being the stuff you copied before, which you can paste with rightclick->paste.
- Execute "git add -A ."
- "git push -u upstream yourbranchname" with your branch name being the branch you're on which has the mirror.
- This will create a branch on the upstream itself, use it to make a PR.
Checking a pull request locally (mainly for maintainers)
- Do "git fetch <remote> pull/<pr>/head:target_branch" , for example "git fetch upstream pull/26271/head:upstream-merge-26271".
- Then you can checkout the target_branch.
- Apply your changes like you would do normally.
- 'git add .', 'git commit -m "message"', 'git push --set-upstream upstream target_branch'