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

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).

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.

   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?

   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. ;-) )


> 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).


Thanks!

Steven Rowat


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
>>>
>>>
>>
>

Received on Friday, 2 December 2016 01:33:13 UTC