Re: Using GitHub for Verifiable Claims Issues and Edits [Was: Re: Verifiable Claims Telecon Minutes for 2016-11-29]

> On Dec 1, 2016, at 5:32 PM, Steven Rowat <steven_rowat@sunshine.net> wrote:
> 
> Greetings,
> 
> I've forked to a new thread on using GitHub for VC because learning how to do this was suggested for everyone, in the Teleconference, and maybe it will be good to have the directions collected.
> 
> After doing the excellent GitHub Flow tutorial that Matt posted [1], then reading another very helpful overview I've found [2], and then downloading GitHub Desktop and doing its tutorial, I think I know enough at least to ask questions about what Gregg suggested. I'll put them inline below.
> 
> [1] https://guides.github.com/introduction/flow/
> [2] http://alblue.bandlem.com/2011/12/git-tip-of-week-forking-and-pulling-vs.html
> 
> On 12/1/16 12:03 PM, Gregg Kellogg wrote:
>> on the GitHub page for a specific file
>> (e.g., https://github.com/opencreds/vc-data-model/blob/gh-pages/CONTRIBUTING.md),
>> if you have edit rights on the repository (if you don’t you can fork
>> the repository using the button in the upper right).
> 
> Q 1: Are there important functional differences whether I fork the repository to a branch on the GitHub site, or into the GitHub Desktop application on my computer? (The answer might vary depending on the situation, but I have to do one of these things, and at the moment don't know whether it matters which one I do).

“Forking” is the act of making a copy of the base repository under your own account. It retains a link back to the original repository so that you can do a pull request to merge changes back into the main repository.

“Cloning” is the act of making a copy of a repository on your desktop. From here you can synchronize changes made at the remote with your local copy, or push changes made locally back to the remote repository.

The mechanism I described allows you to make changes on a repository (as encouraged, by creating a new branch) on the remote repository. This could either be the main repository, or your fork.

Note that there are different ways of working on your desktop. There is the Unix “git” shell command, which is used by GUI software to actually perform the work. GitHub also has their own Desktop software. I use SmartGit [1], which I find quite easy to use; it’s free when used for open-source.

Many light tasks can be done entirely on the GitHub website, as I attempted to outline.

> 2. I'm unsure of the relationship of the word "repository" to the files that are shown on the directory you give. Your example, "CONTRIBUTING.md", is of course there, but so are several others, one of which is an "index.html" and appears to be the raw HTML master of the data model, that we view online in our browsers.

A repository represents the state of the set of files being managed, including all modifications to these files. As files are contained in a directory structure, you can navigate to any given file from their website, or on your local website. By selecting a branch or commit, you can get to any version of that file as well. The link I gave <https://github.com/opencreds/vc-data-model/blob/gh-pages/CONTRIBUTING.md <https://github.com/opencreds/vc-data-model/blob/gh-pages/CONTRIBUTING.md>> is a reference to the CONTRIBUTING.md file on the gh-pages branch of the "vc-data-model" repository within the “opencreds” account. The file may also exist in commits and other branches.

GitHub does a good job of showing some files formatted (Markdown–“.md” in particular). It does not show formatted versions of HTML files, but there are other services (see rawgit.com <http://rawgit.com/>, for example) that will show an HTML formatted version of HTML files in github. The UI for looking at a file also allows you to see the raw data, and the history of changes to that particular file.

>  Q 2a: Does "repository" refer to all the files together, plus the management system that keeps track of changes to them? All of it together? Or is the word "repository" used to refer to single files, like the "index.html" and "CONTRIBUTING.md", separately?

“Repositories” refers to the set of files and Git metadata about those files, including the revision history. If you clone the repository, you’ll see all of the files for the particular branch you have active, and other data in the “.git” directory which keeps track of the state of the repository. Using the “git” command (or your favorite GUI), you can affect your local state of the repository, by, for example, changing the branch you’re looking at.)

>  Q 2b: When I'm viewing a single file in GitHub (say the "CONTRIBUTING.md" in the link you gave), and I create a branch and "fork the repository using the button", as you say, then am I creating a branch that includes only that file, or am I necessarily forking the whole repository, no matter what file I'm viewing? (This is the same question as Q2a, really, but I need to be sure I understand what's going on here, so I don't think it hurts to get a backup answer in this case. ;-) )

No, you’re taking a branch of the repository, and changing only the content of that file. When you make a change, it creates a new “commit” with the delta of all the files in the repository which were changed. This interface only allows you to change a single file, so you have a new branch containing the state of all files from the branch you started with, plus a single commit with the specific changes you made to a given file. Branching and committing is quite light-weight, so you don’t really need to worry about the overhead involved with doing this.

The UI allows you to create a new branch for your commit. There’s a separate operation to fork the repository, which you may need to do if you don’t have permission to edit the main repository.

Note that the web UI is really intended for very small edits (e.g., simple grammatical or spelling errors), not for larger edits.

>> there is an edit tool (a pencil icon) near “Raw”, “Blame”, and
>> “History”. If you click this, you can edit the file in it’s source
>> form.
> 
> Q 3: I see that "index.html" is in raw HTML: is this is where all the editing will occur? --I've done that, but a decade ago, and if at all possible I'd like to edit in the English language, since the HTML is all finished; it's the content that's at issue. Is there a workaround for this, either on a GitHub fork or a GitHub Desktop fork, that would allow relatively painless viewing of the edited/committed content as rendered HTML while editing (or at least alongside).

If you want to change an HTML file, you need to edit it’s source. There are tools that allow you do do this WYSIWIG, but they tend to mess up the formatting of the file, and add a lot of garbage. For ReSpec documents, edits really need to be done to the raw source of the HTML. For many small edits, this is pretty easy, but somethings may be too difficult if you don’t have those particular skills. In this case, you should simply create an issue to be considered by one of the editors. Typically, there will be a couple of primary editors of a given spec who do 90% of the work. Do too much, and you may be asked to become an editor and take on a bigger workload!

> Thanks!
> 
> Steven Rowat

Gregg

[1] http://www.syntevo.com/smartgit/

> At the bottom, after your commit changes, you have the option to
>> “Commit directly to the gh-pages branch” (which should _never_ be
>> done) or “Create a new branch for this commit and start a pull
>> request”. Select the second option, and when you commit the changes,
>> it will automatically create a pull request for someone to choose to
>> integrate, or use as the basis for discussion.
>> 
>> If you do it in a forked repository, you may need to select where the
>> pull request will be made, to ensure it goes back to the original
>> repository.
>> 
>> There remains an issue about keeping your fork up to date, but you can
>> always delete the fork after your request is accepted and merged.
>> 
>> Gregg Kellogg
>> gregg@greggkellogg.net <mailto:gregg@greggkellogg.net>
>> 
>>> On Dec 1, 2016, at 10:50 AM, Steven Rowat <steven_rowat@sunshine.net
>>> <mailto:steven_rowat@sunshine.net>> wrote:
>>> 
>>> On 12/1/16 8:20 AM, Daniel Burnett wrote:
>>>> keep your local copy synced with what's on the server.  Again, none of
>>>> this is super difficult, but there are definitely more steps involved
>>>> than for creating issues, and that's because pull requests assume you
>>>> are actually editing your own local copy of the files (meaning not
>>>> just using a web tool as with GitHub issue creation).
>>> 
>>> Aha! So that's where the mysterious branched document resides: *on
>>> my machine*! (Strikes his head with his palm).
>>> 
>>> Thank you, that's exactly the kind of basic thing that an
>>> experienced coder would understand from seeing the Github
>>> instructions, and which I didn't.
>>> 
>>>> I should have time to send something next week and, as I said on the
>>>> call, am offering to do a mini-review of those steps week after next
>>>> when I can next be on the call.
>>> 
>>> Good, I look forward to it.
>>> 
>>> And/or, if anybody knows of an existing tutorial link, "Github Pull
>>> requests for Dummies", please don't hesitate to post it. :-)
>>> 
>>> In this vein, there's an interesting new effort at MIT that has
>>> created "Gitless", which runs on top of Git (though not at GhitHub
>>> yet I assume), and apparently removes some of the (less necessary)
>>> staging complications.
>>> 
>>> http://news.mit.edu/2016/gitless-making-it-easier-to-collaborate-on-code-1025
>>> 
>>> Steven
>>> 
>>> 
>>>> 
>>>> -- dan
>>>> 
>>>> 
>>>> On Thu, Dec 1, 2016 at 10:46 AM, Steven Rowat
>>>> <steven_rowat@sunshine.net <mailto:steven_rowat@sunshine.net>> wrote:
>>>> 
>>>>   On 11/29/16 9:32 AM, msporny@digitalbazaar.com
>>>>   <mailto:msporny@digitalbazaar.com> wrote:
>>>> 
>>>>       Manu Sporny:  Issues in the issues tracker, as you find them in
>>>>         the spec, please write them in the issue tracker or they
>>>>       will get
>>>>         ...
>>>> 
>>>>       Dan Burnett:  About Pull Requests - PRs are the way to propose
>>>>         specific changes to the document. You edit the document
>>>> and push
>>>>         that edit up such that it can be reviewed, including by the
>>>>         editors, once that's done it can be applied to the
>>>> document. The
>>>>         editors will encourage people to do that. I know some people
>>>>         haven't done that before.
>>>> 
>>>> 
>>>>   I'll report that I've just read the current data model and use
>>>>   cases for VC, and I added:
>>>>   4 Github issues for the data model
>>>>   13 Github issues for the use cases.
>>>> 
>>>>   I was brand new to Github so I'll report for others like myself
>>>>   that it was painless, even pleasant. :-) .  All it took was
>>>>   another new password.
>>>> 
>>>>   About half my issues are minor grammatical issues, which I think
>>>>   should be done at some point but aren't urgent. Several though,
>>>>   I've taken issue with meaningful text, so I hope that people will
>>>>   look at them and comment (yay or nay or changes).
>>>> 
>>>>   In terms of Pull Requests as Dan spoke of:
>>>>   It certainly occurred to me that it would be simple if I could
>>>>   make the minor changes on a branch of the document myself, because
>>>>   I doubt if anyone's going to complain if I change "knwoing" to
>>>>   "knowing" (a real example).
>>>> 
>>>>   But, I looked at Github's explanation of the Pull process, and
>>>>   backed off. Yep, that's for coders. There are about ten different
>>>>   'but if A happens, do B' statements, on the directions page, some
>>>>   of which use words whose meanings I don't (yet) know.
>>>> 
>>>>   What I'm hoping for is if someone can give directions for the
>>>>   simplest Pulls that you're looking for, just like the VC Minutes
>>>>   gave for the Issues, which were beautifully described. Something
>>>> like:
>>>> 
>>>>   To Do a Pull:
>>>>   1. Go to X Github page.
>>>>   2. Punch Button Y.
>>>>   3. Edit the document, using standard cut and paste.
>>>>   4. Punch Button Z.
>>>> 
>>>>   :-)
>>>> 
>>>>   Steven Rowat
>>>> 
>>>> 
>>> 
>>