• You've discovered RedGuides 📕 an EverQuest multi-boxing community 🛡️🧙🗡️. We want you to play several EQ characters at once, come join us and say hello! 👋
  • IS THIS SITE UGLY? Change the look. To dismiss this notice, click the X --->

Guide - Git: Open Vanilla "Forking X" Workflow (1 Viewer)

Knightly

Knightly

Moderator
Joined
Jun 28, 2014
RedCents
19,602¢
Pronouns
He/Him
Get the Repo​

  1. Create an account on GitLab.com and sign in.
  2. Navigate to https://github.com/RedGuides/openvanilla
  3. Click Fork
    • 1644127752894.png
  4. If it prompts you for a namespace, choose your account
  5. It will fork and you’ll be looking at something that’s pretty much identical to what you were just looking at. Note that the project ID will be different and you’ll see the fork information:
    • 1644127767201.png
  6. On this new project, go to Settings in the left hand menu and choose “Repository”
  7. Under the heading “Mirroring Repositories” click the “Expand button and enter the following settings:
  8. It will take a few minutes to update and then in the “Mirrored repositories section you will see the status and when it last updated:
    • 1644127791540.png
    • Clicking the refresh button will force it, but GitLab will also handle it automatically for you.
  9. You now have your own personal copy of the Open Vanilla repo.

Checkout your copy of the Repo​

  1. You’ll need your repo URL for this, which you can get by going to Gitlab. Choosing Projects -> Your Projects, and then selecting “YourName / OpenVanilla” – make sure you do the one under your account and not the one under RG Creators. Once you click on it you should see YourName > OpenVanilla > Details at the top. Click the “Clone” button and copy the https URL. (In the screenshot it will show my name, but you want your name):
    • 1644127826689.png
  2. Clone this URL into a local repository using your tool of choice. If that’s the command line:
    • git clone https://gitlab.com/YourNameHere/openvanilla.git
    • (this would create a folder in the folder you’re in called “openvanilla”
  3. Go into that directory, you’ll be on the “redguides” branch
    • cd openvanilla
    • git branch
      • (This will show * redguides – the branch you are currently on)
  4. You don’t ever want to commit to the redguides branch because that will break your sync with RedGuides (“upstream”). If you commit to the redguides branch, when the GitLab updater tries to sync you it will see that you updated and RG updated and it won’t know how to reconcile that. So just create a new branch to work out of.
    • git pull
      • (This makes sure you’re up to date, if you just cloned you don’t need to do this)
    • git branch mydevbranch
      • (It’s a good idea to name your branch for whatever you’re working on. If I were working on MQ2MyButtons I would name the branch something like “devMQ2MyButtons”)
    • git checkout mydevbranch
      • (This puts you on the branch)
    • git branch
      • (You can use this to check what branch you’re on, the * should be beside the branch you just created).
  5. Now you’re ready to modify the files just like you would normally. Perform commits as needed to your branch. Merge into your branch as OpenVanilla updates, all of that is beyond the scope of this. When you’re ready to merge your changes with RG, you’re going to git push
    • git push --set-upstream origin mydevbranch
      • (here, again, replacing mydevbranch with your actual branch name. This is going to create a branch on the GitLab server with the branch that you have locally)
    • (You’ll need to enter your gitlab credentials to push and then you should see your branch on the GitLab.com site)
  6. You can have as many branches as you want to have. A good practice is to use one branch for each plugin or feature that you want to add so you can keep your development efforts contained.

Submit Your Pull Request (PR/Merge Request)
​

  1. Once you have committed to your branch, you’re ready to submit a pull request.
  2. Log into GitHub and select your project. On the left hand menu choose “Merge Requests”
  3. Click New Merge Request
  4. Your repo should be the default Source Branch and the upstream repo (redguides/openvanilla) should automatically be the Target Branch.
  5. Select the source branch that you want to merge from (the one where you did your changes).
  6. Your Target Branch is likely going to be “redguides” since that is what we publish RG from.
    • 1644127862833.png
  7. Click “Compare branches and continue”
  8. Give your merge request a descriptive title. “Add X feature to X plugin”
  9. Give your merge request a description – this is usually where you will write anything that reviewers need to be aware of and what your changes are.
  10. Under Merge options, I usually select both options:
    • Delete source branch when merge request is accepted.
      • This will clean up the branch in your fork when RG accepts the merge request. If you’ve setup mirroring, you won’t need that branch anymore since once the request is merged to branch redguides, it will get mirrored back to you in “redguides”
    • Squash commits when merge request is accepted
      • This allows you to make commits and changes while waiting on the PR to be merged while keeping the commit history to a single commit.
  11. Click Submit Merge request
 
Last edited by a moderator:
I've attached the first draft pdf to the first post until there's time to forum code it. It does have mirroring in it, which I think is good so people aren't having to manually pull every time VV is updated.

I'm open to suggestions on wording and anything I missed as well.
 
@Knightly -- May want to test mirroring on a private repo -- I think Gitlab has a 'bug' (feature?) that tosses auth errors on those. It makes sense given their original intent for the Mirror feature but annoying as hell. I'll look through the PDF today.
 
Private mirroring works. If you have 2FA then you need to use an auth token. I had that in the instructions originally, but I pulled it out because of this primarily being geared toward the VV public repo.
 
Why are you forking the repo ?
Why aren't people just working on feature branches and merging in with a code review into develop, that leads to a stable release branch... then have master locked down to only a limited few that can merge into it?

Also, if people aren't git flow fluent, there are tools out there like GitKraken to simplify the whole feature/hotfix/release branches.
 
Forking is a pretty standard practice when contributing to any open source project. It means that there is less barrier to entry of having to get an account authorized on the repo you're trying to contribute to. I added extra steps to keep it in sync, but that's more for convenience. It's a pretty standard practice not to give everyone write permission to the main repo.

It also prevents stale branches in the main repo that have to be cleaned up. It removes you having to manage branch level permissions to prevent people from accidentally breaking someone else's branch and allows for people new to git to "break" things without worrying there is going to be some impact on the main repo. Anything they do in their fork is reversible with zero impact on anyone else.
 
For sure. In those cases you're likely already managing who has access (versus a public repo where anyone can contribute) so the overhead of setting up a private mirror to a private repo doesn't have any real benefit over just managing access on the original repo itself.

Well, other than the "You can screw anything in this repo up and not worry about it" factor. But you can mitigate that with appropriate permissions.
 
This is currently the case with several of the plugins that we use and it is a matter of trust in those areas. However, in this specific case, it's actually still in the RG repo it's just that plugins setup wasn't really ready for prime time yet so we don't have all of the review and notification workflow setup yet.

As mentioned, once we're ready to use those repos we'll setup the same workflows.
 
You must log in or register to reply here.
Guide - Git: Open Vanilla "Forking X" Workflow
Next unread thread 🦁

Users who are viewing this thread

Total: 2 (members: 0, guests: 2)
Back
Top