Questions about Github. Advice request. Request that somebody edit Beginners guide to github to explain a bit more.

Beginners guide to github got me through my first sheet submission. It's cookbook style steps were adequate (but improvable). 

However my first update to my character sheet is a huge mess. I am wondering if maybe somebody who knows what I should be doing could maybe add a new section for an intermediate guide to github, slowly, step by step, walking a newbie through the process of updating a sheet that already exists. 

If you don't mind, I will explain what I did and what seems to be wrong, what I think I might have to do, and maybe even how I think I need to do it. 

I am hoping somebody can both provide guidance and correction, and in the end maybe somebody knowledgeable can update the beginners guild to include this process. 

OK, so I made a bunch of changes to my character sheet html and css. When I had them how I wanted them, glanced at the main Roll20 repository, saw that, as expected, nobody else had committed any changes nor made any outstanding pull requests, so my base code was the most recent. I went to the folder on my hard drive where my own clone of the repository is stored, opened the .html file, pasted my new stuff in and saved it. Did same with .css. I opened github for windows, It told me 2 files had changed and I used the button in the lower left to "commit to master". 

Then I went to menu/branch/create pull request and created a pull request. This was all pretty much a subset of stuff I had done when I first submitted the sheet and I was happy at it being so easy. 

All fine so far until I saw that "This branch has conflicts that must be resolved". It says it has 223 conflicts that must be resolved! (7 in .css, 216 in html). It has flagged every single change that I made as a "conflict"! As far as I can tell, there does not seem to be a button that says "just use the new damned file", nor any buttons attached to the 'conflicts' that says ('keep the old stuff' or 'use the new stuff'). As far as I can tell (from https://help.github.com/en/articles/resolving-a-merge-conflict-on-github) it has created a brand new version of the files that is full of 'conflict markers', and I am supposed to go through that and remove all the conflict markers that it just added! along with all the code from the old version that I don't want to keep.

Now I suppose that 223 conflicts will only take about an hour, and there is at least a 50% chance that the process will not introduce any new and totally unnecessary bugs due to failing to remove again a line of code that I had previously removed, or accidentally removing a line of code that I had already told it to add, but I can't help but thinking that this is a totally and completely stupid process that is at least as likely to introduce new bugs due to unnecessary editing in the actual step of moving things into production as it is to avoid errors from branching issues. So I can't help but think that I did something wrong and there was a simple way to avoid this. 

I am going to take a small digression from the character sheet, and mention that I did the exact same thing to a javascript file in the api-scripts repository pull request. It seems to think that .js files are binary files, so it says that there are differences, but will not show the differences. I pressed the "resolve conflict button" and it said warning this will commit to master. After trying various things, I said "ok", and now I can't see anything in my downstream repository. I am not certain that the "resolve conflict" button did not just blank out my downstream. Or maybe it did not, it just thinks it is binary, I have no clue. Anyway, unless pressing the resolve conflict button made it use the new .js file as the accepted one, that pull request is messed up as well. It used to be possible to look at the .js file. Now I can't. Not certain what is in it.  (Note: I think I have fixed this by just committing a 2nd time. )

OK, so anyway, I have been doing some reading. 
https://app.roll20.net/forum/post/5809354/slug%7D suggests that I should be creating branches, but the experts (while trying to tell him how to do that), don't really tell him how he should be managing his sheets. 
https://app.roll20.net/forum/post/7051463/slug%7D does suggest having one separate branch for each sheet. Several people start to explain good branching practice, but then give up and say it is too complex a topic. Once again, would be very nice if somebody made a good cookbook wiki that has nothing but best practices. 
https://app.roll20.net/forum/post/4226001/slug%7D has 

The "Merge remote-tracking branch" commit is from when you updated from Roll20's "master" branch. Since your pull request is going to the same branch, all it's really doing is helping to avoid merge conflicts. (And, since the devs aren't going to spend time resolving merge conflicts, merge conflicts mean rejected PRs.)

But does not really say much about how to do that often so that merge conflicts go away. It also has a nice link to a pull request that has this comment.

You have some deleted files from other sheets. The easiest, and most consistent, way to make sure your branch is up to date is to delete your branch after I have accepted your PR. Then when you're ready to make a new one, create a new Fork, add your changes, then open the PR. That way you are always working withe the newest code.

Just to be clear, is the easiest way to create a new Fork, or a new Branch? In any case, this seems like very good advice and if it is, ought to be viable where more people can see it easier. 

So anyway, what I would really love to see is some people who really know what they are doing, hash out a set of best practices, and update the beginners guide to gethub giving some cookbook style advice that will take a newbie from creating a new sheet, through multiple updates to existing sheets. 

Thoughts? Volunteers?

The biggest problem is that the guide only briefly mentions Git(which GitHub is built around), and people should learn how Git works to be properly able to understand GitHub.

As you noticed, it teaches you enough learn some basic stuff, but when error occurs, it all boils down how Git as a version control system works, and not about GitHub that is just a partial graphical interface to interact and host Git-tracked project.

I unfortunatly don't know it we'll enough to be able to improve on the guide to incorporate everything I think would be needed.

Oh yeah, that thread. I spent an hour or two trying to figure out if I can explain everything, and had to give up as I realized I don't grasp the subject well enough to teach it to others, as well as one of the few times I noticed I reached the edge of my capability to express myself in English(that isn't my native language).

But yeah, we should at least start to pool together the best Git and GitHub guides that have helped us learn it and would work as an more robust introduction to those who wan't to contribute. It have served many, but really only shows how to do the simple stuff without explaining what happens in the background.

Edit: Unfortunately I don't know well enough what went wrong in your specific case, so can't help you there, but did you update your repository with the changes that had occured in the Roll20 repo? Once you have made a fork of an repo, you need to keep your repo up to date for you to be able to keep sending PRs in a good fashion. And did you make your original sheet PR from the master branch or another branch when you submitted it to Roll20? Which branch did you make your new PR from, and had that branch been updated to Roll20 repo's current state?

The most crude and simple solution is just to create a new for of the Roll20 repo, apply the changes you want, and submit a new PR from there to the Roll20 repo. But you wouldn't be closer to avoid the same situation from happening in the future nor understanding either Git or GitHub better.

Professionally I found the Atlassian explanation very helpful. I have to administer Atlassian Bitbucket etc., at work.

https://www.atlassian.com/git

This solves it all:

https://imgs.xkcd.com/comics/git.png

Natha said:

This solves it all:

https://imgs.xkcd.com/comics/git.png

Sadly, Natha, I've had to follow that exact process... :(

I like to think that I have figured out quite a bit about what git is doing and why. What I am unsure about is what I need to do and how to do it. Which is to say, when I do something, I usually know what I did and why. But I often don't know what I should have done instead.

For example, when I created the pull request, it said it was incorporating 6 separate commits, including all the commits that were included in last weeks pull request. I think I understand that, and I think that is not really what I want, and I suspect it is at least part the reason it says there are 'conflicts'. What I am not certain of is what I ought to do to change it going forward. I (now) suspect it has to do with branches and/or forks, but am still trying to put together what exactly I need to do for next time. 

Andreas J. said:

Edit: Unfortunately I don't know well enough what went wrong in your specific case, so can't help you there, but did you update your repository with the changes that had occured in the Roll20 repo? Once you have made a fork of an repo, you need to keep your repo up to date for you to be able to keep sending PRs in a good fashion. And did you make your original sheet PR from the master branch or another branch when you submitted it to Roll20? Which branch did you make your new PR from, and had that branch been updated to Roll20 repo's current state?

There were no changes in the roll20 repo, except for the pull from my repo that came from my previous pull request. I had assumed I would not have to update both ways, but am now wondering if I should have. The only fork I made was long ago when I first installed git and looked at the api-script repository. I have not made any forks or branches since, so the pull request was from my master branch (my only branch).

I keep the projects that I am working on up to date - in that I am the only person working on those projects, so they are never out of date. But I don't do anything to make them up to date, I just check to see if anybody else has made any commits or pull requests. If not I treat it as up to date. 

That is kind of why I would love to see cook-book style best practices procedures written out. (a) this is what we are going to do, (b) this is why we want to do it (c1 - c9) these are the detailed steps on how to do it. Explain all the common things that are done, explain why they are done and the order they need to be done, and how to do them. 

OK, so it sounds like what might be best practice (and yes, I am willing to take best practice advice from an xkcd cartoon) is to delete my repository, make a new one. have it update my files. Fork it. branch for one specific project. Commit to the new branch, push the new branch, make pull request from new branch. After pull request is done, delete new branch. 

Next time I have an update: sync files, then make new branch for project. 

Does all that sound about right and best practices?

Chris D. said:

 Fork it. branch for one specific project. Commit to the new branch, push the new branch, make pull request from new branch. After pull request is done, delete new branch. 

Do not delete a branch until it have been merged! After it have been merged to the Roll20 repo you can delete it, but remember there is no hurry with deleting stuff. Even if deleted branches are recoverable for some time, it's best to not delete things until you are very certain it have been saved elsewhere.

And yes, it's really best practice to have your master branch untouched, and work in separate branches on things. The fact that you have kept your repo up to date with Roll20 is a thing I missed earlier but that is the most common problem people usually have.

I had assumed I would not have to update both ways, but am now wondering if I should have.

You don't update it both ways. If I create 'SWfix' branch, I would then submit a PR to Roll20 master repo from my 'SWfix'-branch. Then the 'SWfix'-branch's PR is merged to the official Roll20 master repo, I then update/sync my 'master'-branch with all the new changes in the Roll20 master repo, and among them are the changes done in the 'SWfix'-branch. If I at this point would try merge my 'SWfix'-branch into my own 'master'-branch I'd likely get merge conflicts as these changes aren't up to date with eachother. The 'SWfix'-branch serves no purpose any longer as it's content have been merged to my master and Roll20 master, and on top of this it's slightly out of date with both. If I'd try to update/sync my 'SWfix'-branch with either my 'master' or 'Roll20 master'-branch these same merge conflicts might occur as I'd try having the same changes done twice.

Personal anecdote of similar situation: I myself have an several months old branch with a worth-in-progress sheet improvement going, but as it have with time diverged from the actual sheet(I've done smaller improvents to the sheet that got merged into the Roll20 repo) so I too accumulated file conflicts and such. I may or ma not have solved the conflicts but basicly I should start from scratch with those things as I'd have to spend way too long to check all the conflicts and so on.

Andreas J. said:

Chris D. said:

 Fork it. branch for one specific project. Commit to the new branch, push the new branch, make pull request from new branch. After pull request is done, delete new branch. 

Do not delete a branch until it have been merged! After it have been merged to the Roll20 repo you can delete it, but remember there is no hurry with deleting stuff. Even if deleted branches are recoverable for some time, it's best to not delete things until you are very certain it have been saved elsewhere.

If you only use a particular branch for one sheet why do you need to delete the branch especially if you are the only one working on the sheet? 

branch for one specific project.

Oh, and the thing about only working on one sheet per branch, comes from the fact that it's best practice to work on one feature per branch in general. If you work on two features at the same time, submit a PR, and some problems are found in in one feature but not the other, then it stops the merging the PR and both features, even if only one of them contained a problem.

Hm, I'm starting to having some ideas on how to improve on the article. But it's possible I'd just make a separate guide on how to work in the command line environment. We'll see. But at least the guide could be updated to include how to keep your fork up to date with the Roll20 master, it doesn't address how it's done.

David said:

If you only use a particular branch for one sheet why do you need to delete the branch especially if you are the only one working on the sheet? 

Well I don't know for a fact that I should, but I have observed that when I create a new pull request it says that it is for all the commits I have ever done, even ones that were included in previous pull requests that were previously pulled. I am not certain it is, but this strikes me as weird and undesirable. My guess is that if I make a brand new branch off of master,  the pull requests from that branch might list only the commits to that new branch, which strikes me (I think) as more desirable behavior. Then, when the pull has been performed, the branch can be deleted since I will never commit to that branch again, because otherwise it would be saying that it is committing the same things again. I think.

Obviously the branch does not strictly need to be deleted if you don't want to. But I think you do want to remember which branch(s) you are currently working on, and just getting rid of the old ones is a simple way to do that. There may be better ways. As I understand it the "standard" way is to "merge the branch back in". But from what I am hearing, deleting it is just as good if not better. 

Alright I've made a minor update to the Beginner's Guide to GitHub by adding a few links to additional learning resources.

I managed to find a well-made Youtube guide that teaches the basics on GitHub while also explaining Git in simple terms, in short segments.

Git and Github for Poets covers all the basics, but at the end it contains even a video on Merge Conflicts! (9 min long).

I briefly listened/skimmed through them and it seems like an absolute goldmine, as it's made for a nontechnical audience while showing how everything can be made in the browser. From now on this will be the go-to into to Git/GitHub. 

Greetings,

Git has a learning curve like much of development. As posted above the Atlassian Git tutorial can be helpful. I recommend learning Git via command line rather than the App. Code Academy has a tutorial for Command Line and for Git. When working on my personal sheets, I use Git for Windows when I find myself away from my Unix workstations.

Some tips that I use when doing my personal sheet work:

• Update your fork after every Tuesday! Just put in a Pull Request that has the Roll20 master branch merging into your fork master. This will keep your fork up to date.
• Use Branches. Before starting a new project always make sure you are on the master branch and git pull after completing the above mention updating of your fork. Then do git checkout -b nameofbranch . This will create a new branch and check it out. Provided you have followed all of the steps, you will have a nice updated branch that is the same as the Roll20 master. Complete all your work then git push this branch to your fork. You can then do a pull request to merge this branch into your fork's master OR you can pull request to merge this branch directly to the Roll20 master repository. If you do this second option you need to make sure you are doing the update your fork after every Tuesday. Other wise your master fork will be outdated and you'll have issues.
• Use a new Branch for each sheet! If you work on multiple sheets use a different branch for each sheet. This will allow you to submit different pull requests for different character sheets. This is a best practice because if something in one pull requests is screwed up it does not delay updating the other sheet's fixes. Just make sure before starting work each time that you do a git branch to verify that you are on the right branch. git status will also tell you what branch you are on at the top.
• After a Branch is merged into Roll20 master delete it. You want to always be working on a branch that is relatively close to master. Branches will typically get a little bit behind and that is generally okay. If your branch gets really far behind you'll likely run into issues especially if there is more than one sheet author. After your branch has been merged into the Roll20 master delete it and make a new one for the next feature following the above steps.
• git status is your best friend! Do it a LOT! Make sure you're on the right branch, that you're updates are ready for add, that they have been added, and then committed. I probably git status about every other command.
• git reset --hard master  can be useful if you screwed something up but be careful & know why you're doing it! This will reset your files and delete your changes that have not been pushed. Save backups and I would not recommend using this command if you do not frequently push updates of your branch to your fork.
• When all else fails, backup your work and delete the clone. This is not an ideal option because you'll have to download gigs of character sheets again but it will generally solve your trouble.

I hope that helps. Git was a struggle for me as well. :)

- Cassie

Cassie said:

Greetings,

Git has a learning curve like much of development. As posted above the Atlassian Git tutorial can be helpful. I recommend learning Git via command line rather than the App. Code Academy has a tutorial for Command Line and for Git. When working on my personal sheets, I use Git for Windows when I find myself away from my Unix workstations.

Some tips that I use when doing my personal sheet work:

• Update your fork after every Tuesday! Just put in a Pull Request that has the Roll20 master branch merging into your fork master. This will keep your fork up to date.
• Use Branches. Before starting a new project always git pull after completing the above mention updating of your fork. Then do git checkout -b nameofbranch . This will create a new branch and check it out. Provided you have followed all of the steps, you will have a nice updated branch that is the same as the Roll20 master. Complete all your work then git push this branch to your fork. You can then do a pull request to merge this branch into your fork's master OR you can pull request to merge this branch directly to the Roll20 master repository. If you do this second option you need to make sure you are doing the update your fork after every Tuesday. Other wise your master fork will be outdated and you'll have issues.
• Use a new Branch for each sheet! If you work on multiple sheets use a different branch for each sheet. This will allow you to submit different pull requests for different character sheets. This is a best practice because if something in one pull requests is screwed up it does not delay updating the other sheet's fixes. Just make sure before starting work each time that you do a git branch to verify that you are on the right branch. git status will also tell you what branch you are on at the top.
• After a Branch is merged into Roll20 master delete it. You want to always be working on a branch that is relatively close to master. Branches will typically get a little bit behind and that is generally okay. If your branch gets really far behind you'll likely run into issues especially if there is more than one sheet author. After your branch has been merged into the Roll20 master delete it and make a new one for the next feature following the above steps.
• git status is your best friend! Do it a LOT! Make sure you're on the right branch, that you're updates are ready for add, that they have been added, and then committed. I probably git status about every other command.
• git reset --hard master  can be useful if you screwed something up but be careful & know why you're doing it! This will reset your files and delete your changes that have not been pushed. Save backups and I would not recommend using this command if you do not frequently push updates of your branch to your fork.
• When all else fails, backup your work and delete the clone. This is not an ideal option because you'll have to download gigs of character sheets again but it will generally solve your.

I hope that helps. Git was a struggle for me as well. :)

- Cassie

So, to show you how mixed up I am...when I go to GitHub, I see this:

Trying to follow your first bullet advice, I click on the Pull request link (directly to the left of Compare), and I see this:

and this is what confuses me...because the direction of the arrow makes me believe I'm not going to be getting the latest updates from Roll20, but "pushing" my stuff to it.  It seems like GitHub uses push and pull in a counter-intuitive way and I'm afraid to do anything for fear of screwing something up. Especially since I see those changes to prowlers and paragons which has already been incorporated into the master list and are live on Roll20.

Am I reading too much into this stuff and should I click that big green button? Or do I need to change something first? Whenever I try try swap around  the repos in those drop-down lists it never works, I just get Roll20 pointing to itself or me pointing to myself...I'm not an idiot, but this stuff sure makes me feel like one...then again, perhaps I am an idiot... :-/

Finderski said:

Natha said:

This solves it all:

https://imgs.xkcd.com/comics/git.png

Sadly, Natha, I've had to follow that exact process... :(

I was half joking as I have to do the same regularily. Git eludes me. Even using branches.

Finderski,

Change the left one to your fork then press Compare across forks and set the right drop down to the Roll20 Master. I know the Compare Across Forks step is confusing. Maybe there is a better way to do it. I just don't know how.

I agree the arrow pointing left feels counter initiative. I promise you do not have the permission to hurt the Roll20 master repo. :) You may want to keep extra backups while you're learning Git commands as you could hose your fork. The Roll20 master is safe from the typical users mistakes. That's why Natha's cartoon is funny and true. :)

- Cassie

I used to delete and re-fork because I wasn't sure how to keep my fork updated... Then I learned a method; each week after everyone's PR's have been merged, I go to the roll20 repo and choose "New Pull Request" and then "Compare across forks" , change the Base to my fork, type in something like "Update my fork" and then "Create Pull Request".  This updates my master fork on my github account for roll20.  I also use the desktop gui which will auto-sync with my fork.  I normally do local edits on their own branches and merge them to my online account's Master fork of roll20.  Later I create PR's to roll20 repo from my Master fork. Should I be submitting PR's from separate sheet commits from their own branches?

Vince said:

Should I be submitting PR's from separate sheet commits from their own branches?

It would certainly migrate the risks if you happen to make a mistake while doing your stuff. If the error occures in the branch you are working on, in worst case you'd start over by creating a new branch from your intact master branch.

And if you want to work on more than one sheet concurrently, separating the work done by branches results in you being able to make separate PRs on them, as well as the previous benefits.

Vince said:

Should I be submitting PR's from separate sheet commits from their own branches?

It really just depends. Sometimes I merge everything from my branches into my fork's master and put in one pull request. I then just comment on all the changes as our template requests. I do this especially for smaller feature requests & bug fixes change.

Other times I submit PRs directly from branches. For example I recently completed a sheet for Night Witches and in the same time period updated the Shadowrun 5e sheet with a bug fix. If I had merge these branches into my fork's master and then put a pull request in from my fork's master to Roll20 both of these updates would have potentially been delayed if errors were found in either one of them. To avoid this possibility, I put in pull request to the Roll20 master directly from my nightwitches branch and my shadowrun5e branch. Since these pull request come directly from their own branch they are two separate Pull Requests. This makes them easier to revert if needed and do not impact each other.

This second method would be over kill for the typical sheet author making incremental updates on a single sheet. Please not every one start doing this as I would really do not want to review all the extra pull request for minor commits. ;) It can be useful when working on separate sheets or for you in particular Vince it may occasionally be a better option since you maintain one of the larger sheets. I'd trust you to know what's best and both methods will work.

So...if I do the branching thing...does that essentially double the space needed on my computer? Meaning, I have my Master branch which has ALL the character sheets from the roll20 git (or whatever it's called) and I'd hate to have 2 different directors with all the sheets.  Heck, I wish there was a way to ignore all the other sheets and only deal with the character sheets I maintain...I've lost a lot of hard drive space for things I don't care about. :(

Finderski said:

So...if I do the branching thing...does that essentially double the space needed on my computer?

No, that would be some horrible usage of space, and someone would get fired for creating such a bad system. For each branch you create, I'd say the disk space increase is only comparable to the difference between the branches you have.

So if the Roll20 repo takes 1Gb space, and you decide to have one extra branches working on a larger than average sheet and change up some images used and whatever, you'd probably only use up just a few Mb extra. That's assuming you have lots of changes between your branches.

This is the closest I got to find a real answer to your question on a quick search

I think what happens is - your online github has a copy of all the files, including all the branches.

When you choose a branch on desktop github, it deletes the files from your hard drive that dont exist in that branch, and adds the files that do.

Usually these are very small files, so it happens very quickly.

I'm curious what happens if you dont have an online connection. Maybe the files are stored in a hidden folder, or compressed form on your hard drive and you odnt need the online connection. Either way, when you switch branches, the visible files in your github directory change to match your branch.

All of this is gold. Like I said, we need to boil down all the important bits and put it where it is easy to find. 

I've been avidly following this thread and already have it bookmarked. I agree with Chris, having all of this on the wiki would be very helpful.

Chris D. said:

All of this is gold. Like I said, we need to boil down all the important bits and put it where it is easy to find. 

As I said earlier, I updated the Github guide with links to a short and excellent youtube series explaining&illustrating how Git&Github works(and requires no prior technical understanding). IMO it does a good job to explain what's needed, bett:

Git and Github for Poets Youtube Tutorial

10-20 min long videos for non-technical people that teaches the basics on Git and Github, showing how to work with Github in the browser, but also have an intro to using the command line. It's made in 2016 but doesn't seem to be dated on a quick look(March 2019)

• 1.1 Git/GitHub intro 14 min

• 1.2 Branches 12 min

• 1.3 Forks and Pull Requests 13 min

There are also a "Beyond Basics" section that touches subjects like command line intro & merge conflicts

Also added link to how you sync your fork to the original using the browser, as well as linked to this thread there.

I just made some big changes to the GitHub for Beginners document. I made it about 50% longer and rearranged the order of some sections. One of my goals was to make it extremely specific to roll20. For example not just say a generic "commit your changes", but instead describe the process of getting your changes from roll20 into GitHub. I would appreciate if people would look at it and make sure I got it all correct. In particular Is the the process I describe the best practice?

Also, I ended up saying that Andreas J's Flow of: Branch, Commit to the branch, submit a Pull Request from the branch. Wait until the pull request has been done. Then delete the branch, and sync your master from the roll20 master was best practice. 

I used that because nobody else said it was not what should happen, But all the Git documentation that I read says that the recommended Flow is: Branch, Commit to branch. Merge branch with master (which I think also deletes the branch), then make Pull Request from master. 

Which of these two is actually best practice? If anybody else wants to hack away at what I have done feel free. 

Chris D. said:

Also, I ended up saying that Andreas J's Flow of: Branch, Commit to the branch, submit a Pull Request from the branch. Wait until the pull request has been done. Then delete the branch, and sync your master from the roll20 master was best practice. 

I used that because nobody else said it was not what should happen, But all the Git documentation that I read says that the recommended Flow is: Branch, Commit to branch. Merge branch with master (which I think also deletes the branch), then make Pull Request from master. 

Which of these two is actually best practice? If anybody else wants to hack away at what I have done feel free. 

If i understand the processes above, the first method is best for roll20, because if you merge the brances before submitting to roll20, you lose the advantage of working with separate branches. The whole purpose of doing it that way is if, say, you have three character sheets to submit, they each get treated as a separate commit, and roll20 can accept or reject them individually. If you merge the branches into a single master and submit that, it is treated as a single commit (I believe).

Git documentation suggests doing it the other way maybe because for most software projects, its better to make a single commit. I'm guessing? It might also have to do with the assumption that users will be using the command line Git interface, which has more powerful commands than the windows desktop github app - but most roll20 users will be using that I think.

GiGs said:

The whole purpose of doing it that way is if, say, you have three character sheets to submit, they each get treated as a separate commit submission, and roll20 can accept or reject them individually.

But yes, one of the  main points in working in branches is for if you work on several sheets concurrently and split the work into separate branches, while the other good reason is to protect your 'master' branch(which should ideally be identical to Roll20's 'master'-branch). If you mess up your work, you don't have to nuke your whole repository, just the branch you messed up with.

Chris D. said:

In particular Is the the process I describe the best practice?

You additions of the "Sync Files" and "Make a Branch" section are in the right direction, but the informal language together with some ambiguous use of terminology points to it needing a rewrite to make things more clear.

I removed the large sections you added in the beginning as they were both out of place and didn't present information too clearly, risking confusing people with inexact wording and such.

Andreas J. said:

GiGs said:

The whole purpose of doing it that way is if, say, you have three character sheets to submit, they each get treated as a separate commit submission, and roll20 can accept or reject them individually.

GiGs I assume you meant to say Pull Request or submission, because commit(the Git concept) doesn't make sense in this context.

But yes, one of the  main points in working in branches is for if you work on several sheets concurrently and split the work into separate branches, while the other good reason is to protect your 'master' branch(which should ideally be identical to Roll20's 'master'-branch). If you mess up your work, you don't have to nuke your whole repository, just the branch you messed up with.

Yes, I wasn't using accurate git terminology, just using commit in the regular programming sense - which matches submission.

I am not a very good writer, and really do hope that somebody will bash this into a better shape than my first effort. I made a few more edits but they are all minor phrasing things, hopefully improvements. 

Also I totally see your point about ambiguous use of terminology. When somebody uses the wrong term, it can make things even murkier. Some of the things I have read about branching seem to use the term fork almost interchangeably with branch, and leave me even more confused.

That having been said, it is very possible that a lot of my problem is that I DON'T KNOW  the correct terms for some of the things I am trying to say. For example several times in my writing I refer to the "clone files". I mean to refer to the files upon the hard drive that were placed there when I cloned my repository, and that GitHub desktop is monitoring and will help keep in sync with their origin. I have never seen anybody else refer to them as "clone files", but I using that term for want of any other term that I know. Where I am using the wrong terms I would appreciate knowing the correct terms. 

I do want to mildly push back a tiny bit about one deletion. I don't disagree that what I had was not the best possible version, but I do argue that we ought to have something in it's place. 

One thing to understand is that there will be several different copies of your project files that are stored in different places in different ways. This Beginners guide to GitHub will assist you in moving your project changes (ether to character sheets, or API scripts) through the various necessary stages. For each step of the process it is helpful to keep in mind which of the copies are being used or updated. 	
* The main official Roll20 GitHub [https://github.com/Roll20 https://github.com/Roll20] repository has two folders [https://github.com/Roll20/roll20-character-sheets roll20-character-sheets] and [https://github.com/Roll20/roll20-api-scripts roll20-api-scripts]. These repositories reside upon the GitHub servers. You have no direct access to these but can ''request'' that your updates be incorporated. Once your changes make it into here they are "going live" and become part of the scripts and character sheets available to all users. 
* You will "Fork" yourself your own personal copy of the main Roll20 repository. This repository will likely have an https: address such as "github.com/YourNameHere/roll20-api-scripts" This repository is on the Github website/server, and.  
* You will "Clone" your "Fork", which will cause all the folders and files in the repository to be copied to your local computer hard drive.
* All of this is separate from the version of the code that you actually have within Roll20. If you are going to be modifying character sheets then you need to tell Roll20 that you are using a Custom character sheet, and paste the same html and css into both roll20 and the files on your hard drive so they can be uploaded to your repository.

Several times I have read the comment that it is difficult to explain Git to somebody who does not understand how Git works. What I was attempting to do (but I recognize I did a poor job doing it) was lay a foundation of knowledge, so that the subsequent explanations would make more sense. 

The first several times I read the original version of this guide, I did not know what a fork was. I did not know what a clone was, nor how it was different from a fork. Nor what a push did that was different from what a commit did. Once again, I did not know these things even AFTER reading the guide several times. It was not until after doing these things that I finally figured most of them out. 

I thought it could be valuable that we state upfront, in the introduction, what the different data state/stages/versions/whatever are, and that the goal is to move changes through all these stages to the roll20 master. 

I totally agree that the text above is wordy, and repeats concepts that are (now) explained in the sections that address these activities in more detail. But I think it might be valuable that the detail sections fully make it clear what stage the data is in before each action, and where the action transports the data to. I thought that a list at the top of all the places the data resides might be valuable. So once again, I don't defend the exact text above. But I do think that we need to make extra sure that the concepts expressed are fully obvious upon the first reading of the document. even if we have to say some things twice. My opinion only. 

Also, I noticed that the following text

Almost all of the official Git documentation says that what you should do is merge your branches into your own master, and then make your pull requests from your master, or make the pull requests from the branches, then after the pull request has been done, merge the branch back into master (I am not sure if that makes syncing more important or less). The advice I get specifically about roll20 says there are better results from submitting pull requests from your working branches, then synchronizing your master fork with the roll20 master. It would be nice if somebody wise and experienced gave us a definitive best practice.

Was touched, but still present, as if you removed it, then added it back in again. I totally agree that this paragraph, as is, should not remain in the final document. But I assume that you felt, like I do, that it ought to remain there just long enough for this thread to come up with better text. 

Suggestions for what this paragraph should say?

I intended to rewrite that part, but it really needs an own section, and not be sprung on the reader in that section. There and many other places it indeed need rewrite to use the proper terminology, to not confuse readers further. With a disconnected vocabulary it's hard to do a google search on a subject if you don't even have the right words.

If I removed something, I did so consider it's better removed until a something better is written, than letting it stand to confuse the reader further. The guide still need massive revision, but at least the things that are left are somewhat correct.

Yeah that last part I saw as better to delete now and rewrite later, rather than leave it be, as it indeed murkies the water. Could you link to the guide you have been taking about? I searched the web for 'Github Fork workflow' and found a handful of okay articles on the subject, and many pictures that would help people's understanding.

I personally considered that I don't understand Git/Github well enough to explain it well from scratch, but after reading your expansion and contemplated on how few people here actually understand Git/Github, I changed my mind and lowered my standard so that we can have at least some kind of improvement on the article.

 You set things in motion, and that was your intention all along, so all is good right?

And please, say that you watched the three first videos on 'Github for poets' series i linked in the end of the wiki guide we been talking about. Kt does a good job of clearly explaining the basics in a consistent and proper terminology, totals to just to three 10 minute videos that does a better job than the long winding thread we have here or the technically complex guides elsewhere.

Most of the guides I have been reading lately have been the ones you linked at the bottom of the document. The flow document I have been looking at most is one you linked.

• The GitHub Workflow(visualisation)

where the flow is: Branch, commits, pull requests, review, Deploy, merge back into master. 

Which is very different from the flow we recently rejected (Branch, commits, merge into master, pull request). 

Have we actually discussed the advantages and disadvantages of the: Branch, commits, pull requests, review, Deploy, merge back into master. model? It seems to be identical to the one we are proposing except instead of merging back into master, our flow is to delete the branch. I think actually merging it back into master (I would assume it ought to be done before your next sync, but that ought to be checked) might be the correct and best practice. 

Comments?

I had watched one of that guys videos previously, but not any of those three you had listed (I had watched 1.9 on merge conflicts).  Videos are not my learning medium of choice. I just watched them all now, and have to say that watching a guy doing his rainbow dance and making mistakes that he says he ought to edit out (but does not) seems like a poor experience. Strange that you say watching the video's "does a better job" than reading this thread. Surely that is the wrong standard. This thread is meant to gather information, not teach information. 

The correct standard should be the Beginner's guide to GitHub document we are trying to get edited. I would say it is already, as it stands, much better than watching videos. The video's take 39 minutes to watch the first 3, and, while OK for teaching, is almost useless as a technical reference. The guide we are writing however,should, when done, be readable and understood in a fraction of that time, and provide step by step guides for doing precisely what the user needs to do. 

Just to be clear, I do NOT see the primary target audience to be somebody who wants to learn git. We can give references in the More Info section for those who want to learn more. I see the primary target audience to be somebody who a few times per year, wants to push some changes up to the roll20 master repositories, and is looking for some step by step guidance as to how to do it. Just to bring this conversation back full circle, I found the instructions in the original version adequate for my first pull request, but my 2nd pull request resulted in hundreds of merge conflicts. I am just looking for better procedures and clear instructions. So that a year from now, after I have forgotten all this, I can just follow the instructions and get my updates submitted with the least amount of fuss and bother. 

Now that being said, I do feel a certain base knowledge of concepts is important, and that brief statements of what is being done and why are part of the process of explaining how to do something.

I agree that the tutorial should not really have much to do with Git. It should be purely a guide to using the github for desktop application, and be focused purely on how to get stuff into roll20. 

Sure, the video guy doesn't always do a great job, but the three first videos uses the right vocabulary while teaching the basics, which I see as preferred to be known by the user. The rest of the videos doens't contribute as much.

Yeah, Git only should be mentioned in passing(being the actual tool github relies and builds on).

Reason we don't merge our 'work' branch into our own master after we done a successful Pull Request to Roll20's repository: It's because that would lead to our 'work' branch's change trying to be applied twice into our own 'master' when we fetch changes form the Roll20 repo. Our Ull Request's('work' branch) content is merged into Roll20's repository, and then we fetch the changes to our master, after which our master is up to date. If you try do some other way, you likely run into some problems or complications if we in the future try to push changes from our repository onto Rollw0's repository. If you had understood what git/github does at it's core and the underlying logic, you wouldn't be considering this way to merge hour additions in two different ways. The github workflow doesn't quite work identically to a Github fork workflow(look it up). It should finally clear up what the flow is about.

I had thought that Git was smart enough to recognize that the two would be identical and that there was no conflict. But it sounds like the safest thing is to just never plan on a merge. But upon reflection I actually see no reason to actually recommend deleting the old branches ether. 

https://gist.github.com/Chaser324/ce0505fbed06b947d962 which is a tutorial on forking ends with a recommendation that excess branches be deleted, but re-reading it, I think that he is saying that somebody implementing a pull request should cleanup the excess branch from the upstream master. Not that the guy who submitted the pull request should delete his branch.  I have not seen anywhere else where it is suggested that branches be deleted.  Discussion?

I went ahead and changed the name of the section from Merging and Deleting old branches to "Cleanup" and recommended against merging the branches (even thought the desktop app will recommend that you do it). 

I also added https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow to the "more information" section. 

So once again, if anybody has any suggestions or feels that alternate terminology ought to be used, please edit it into the document. Or at least share which proper terms they think ought to be used. I have used the terms I know, so if anybody has better, share. 

The reason to delete the branches, is because otherwise you have problems with keeping your branches updated.

When you fork your copy, you get a version of the roll20 git that existed at that time. When you make a branch, you get a copy of your git, at that time.

While your work on your own branches, over time, the roll20 repository updates and changes, but your local copies don't.

If you keep working on your own copies, making your submits, etc., sooner or later there'll be enough changes in the roll20 repository that you can suffer conflicts when you try to submit: because your working off an outdated base. (I think this is mainly an issue if other people are also submitting changes to the sheets you are working on, but that can happen - but I could be wrong about that..)

If instead, after each push, you delete your own branches, and resync with the source, you keep your local copy updated, and should never suffer conflicts.

Now, I actually think for most people working on sheets, this is a non-issues, because most people will only be working on one sheet and likely they'll be the only person working on that sheet. But as a best practice, it's worth considering - it's a convoluted way (as everything is with github) of avoiding problems down the line.

There is a process of keeping your repository synced with the source, but if you have several branches, you have to do it for every branch, and its npt intuitive. Deleting your branch and creating a new version is actually very quick and easy in comparison.

I often use multiple branches on my fork for multiple sheets.  That said, I also delete these branches regularly to avoid any confusion or future conflicts, after merging commits to my fork and making a pull request to the main roll20 repo.  Github is confusing.  I have found a method that seems to work for me.  I haven't had time to read much of the updated wiki yet... but staying specific to the roll20/github method is a good thing.  No reason to muddy the waters wit more "gitfusion". ;-)  

GiGs said:

The reason to delete the branches, is because otherwise you have problems with keeping your branches updated.

When you ...

If instead, after each push, you delete your own branches, and resync with the source, you keep your local copy updated, and should never suffer conflicts.

There is a process of keeping your repository synced with the source, but if you have several branches, you have to do it for every branch, and its npt intuitive. Deleting your branch and creating a new version is actually very quick and easy in comparison.

I could be wrong, but I think you are lumping two things together. Deleting your old branches, and resyncing your master with the source. 

I THINK, that if you resync your master with the source, and make new branches off of your master (not your old branches), it does not matter whether you deleted your old branches or not. They are orphaned and don't affect anything.

I think. 

I don't have the time this week, but somebody really ought to create two or better yet three roll20 login accounts and play with this. Go through several iterations of our forking workflow without deleting the old branches and see what happens. 

The way I think it works: When you resync your master, it only resyncs the master. The branches remain independent, and are not updated.

It fits my experience (I have resynched a master while having branches), but I am no github expert, so I could be wrong. But it makes intuitive sense: when you sync the master, if it also updated the branch, it could easily mess with changes in your branch.

Yes, if you make new branches off the master after synching it, they'll be updated. But any old branches you have wont be updated (if I'm right), and if you aren't deleting them, you are probably still working in them. Hence you have to worry about conflicts down the road. Thus, its better to delete them first.

GiGs said:

The way I think it works: When you resync your master, it only resyncs the master. The branches remain independent, and are not updated.

This is true.

Chris D. said:

I THINK, that if you resync your master with the source, and make new branches off of your master (not your old branches), it does not matter whether you deleted your old branches or not. They are orphaned and don't affect anything.

I think.

True. Earlier I just pointed out to not be too quick to delete them before Github tells it's safe to do so, as you said some ambiguous things that could be misinterpreted.

Chris D. said:

I don't have the time this week, but somebody really ought to create two or better yet three roll20 login accounts and play with this. Go through several iterations of our forking workflow without deleting the old branches and see what happens.

Why? What have Roll20 accounts to do with anything?

And yes, not deleting unused branches have no effect than to leave them to cutter up your repository. Go look at Roll20's character sheet repository, they have like 30 branches that are god know how old.

Andreas J. said:

Why? What have Roll20 accounts to do with anything?

Can one account fork a repository for which that account is the owner? I thought you could only fork somebody else's repository and it would require at least two accounts to give the forking workflow a solid test. 

The goal would be to make a repository with a file. a readme.md would be sufficient. Fork and clone the repository, then using our workflow make some changes and create a pull request that the original repository merges back in. Then use our workflow to sync the two and have the 2nd repository make some additional updates. will the 2nd pull request say there are merge conflicts? Basically test the workflow as if 2 or 3 separate users were making updates. 

I suppose if you can make multiple forks of the same repository on the same account, then one does not need to do multiple accounts. But when the github for poets guy was showing forking, he used two accounts to do it. 

So you meant to say GitHub account, not Roll20 account. 

Yeah, seems you can't fork you own projects. People can give full permissions to other for a project, so it this playground would be created it wouldn't need to have two accounts, just user privileges on two. One person have the original project, and the other a fork, and both could share maintainer privileges to  each other.

My workflow for editing a sheet:

1. On Github.com put in a pull request using compare across for to merge in the official repository to my fork. Due once every Tuesday.
2. In terminal, go to cd ~/Documents/GitHub/roll20-character-sheets 
3. In terminal in character-sheets, git branch or git status to ensure I'm on master. git checkout master if I'm not.
4. In terminal, git pull to pull down all of those updates I merged in Step 1.
5. In terminal, git checkout -b branchName 
6. Do the necessary update for the character sheet. When I want to save progress do the process below
7. In terminal, git status check for updates, git add the updates I want to keep, git commit -m "updateMessage", git push origin branchName
8. Now all those changes are on the branch on GitHub. If I'm done I continue to step 9. Else go back to Step 6.
9. On GitHub.com, go to your fork and put in a pull request using compare across forks. Be sure to change your branch in the drop down from master to branchName. Review the changes and if they are correct submit the PR.
10. If you want to work on another sheet go back to Step 3.

If you ever have files that are interfering with you changing branches you can do git reset --hard master BUT THIS WILL DELETE CHANGES TO THOSE FILES! So be very careful doing this as you will loose any unsave progress.

After your branch is merged into the official repository delete it. Do not keep working on it. It will get outdated and cause you all sort of problems.

Cassie said:

My workflow for editing a sheet:

1. On Github.com put in a pull request using compare across for to merge in the official repository to my fork. Due once every Tuesday.

What if I told you that this GitHub step could be done easily  done in the command line? Your computer tracks your GitHub repository as a remote for the clone on you computer, but you can add additional remote that you can pull/push from.

If you run the following command:

git remote add upstream https://github.com/Roll20/roll20-character-sheets.git 

you can now pull from the roll20 repo to your own with:

git pull upstream master

(It's standard to call the parent/original repository as 'upstream', but is actually arbitrary) When you pull from this other remote, you have to specify the branch, and 99% it's the master branch we want to pull from. I assume push works only if you have rights on the remote, so I haven't tried that as making PR in the browser is still easier to get the comments formatted better.

Of course, pulling from the upstream repo only updates the local repository on your computer, so you would need to push to you github repo to have both updated. So after setting up the new remote, step one would be:

1. A) git pull upstream master

1. B) git push

1. C) repeat A) and B) for any other branch you need to update