• IS THIS SITE UGLY? Click "RG3" at the very bottom-left of this page to change it. To dismiss this notice, click the X --->
  • You've been invited to attend the 2nd annual "EverQuest Software Awards"

Guide - Git: Very Vanilla "Forking X" Workflow

Knightly

Moderator
Joined
Jun 28, 2014
RedCents
5,085¢
Get the Repo

  1. Create an account on GitLab.com and sign in.
  2. Navigate to https://gitlab.com/redguides/VeryVanilla
  3. Click Fork
    • 1577573594852.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:
    • 1577573663718.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:
    • 1577573715216.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 VeryVanilla 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 / VeryVanilla” – 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 > VeryVanilla > 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):
    • 1577574210718.png
  2. Clone this URL into a local repository using your tool of choice. If that’s the command line:
  3. Go into that directory, you’ll be on the “master” branch
    • cd VeryVanilla
    • git branch
      • (This will show * master – the branch you are currently on)
  4. You don’t ever want to commit to the master branch because that will break your sync with RedGuides (“upstream”). If you commit to the master 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 VeryVanilla 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 GitLab 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/VeryVanilla) 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 “master” since that is what we publish RG from.
    • 1577575566989.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 master, it will get mirrored back to you in “master”
    • 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
 

Attachments

Last edited by a moderator:

Knightly

Moderator
Joined
Jun 28, 2014
RedCents
5,085¢
I do like that post a lot, it's one I've referenced before. But to Sic's chagrin, it's missing forking and pull requests.
 
Joined
Oct 4, 2019
RedCents
992¢
Then debate whether you want to mention Gitlab mirror for upstream syncing... which appears perhaps not to be the original intent (though some gitlab articles bring it up...)

 

Knightly

Moderator
Joined
Jun 28, 2014
RedCents
5,085¢
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.
 
Joined
Oct 4, 2019
RedCents
992¢
@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.
 

Knightly

Moderator
Joined
Jun 28, 2014
RedCents
5,085¢
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.
 
Joined
Feb 24, 2005
RedCents
1,580¢
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.
 

Knightly

Moderator
Joined
Jun 28, 2014
RedCents
5,085¢
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.
 

Knightly

Moderator
Joined
Jun 28, 2014
RedCents
5,085¢
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.
 
Top