>> Eric: We're going to record and it's recording, obviously.
So first things first.
Welcome for this Github training session.
We try to make some progress using Github.
There are people from two working groups here, so a lot of people
from the WCAG working group and also people from the Education and Outreach Working Group
and I'm happy that we get both groups together and in this session.
I think that's really neat.
So, yeah, let's get this started.
So it's basically an introduction.
I didn't want to go into very deep of the details of how Git or Github works.
We will be going into more details with Github, but I want to make it very practical
so you can so basically showing the stuff, that it's important to you working with that stuff.
If you've got any questions, you can always raise your hand
and in the queue using the the IRC channel, it's #github on the W3C IRC channel
and if you haven't haven't checked in there, you should.
But you can always ask me questions and I will try to get to them as soon as possible.
So one important note, of course different editors have different preferences for using Github
and we we probably have edge cases where other people think differently
than I do, which is pretty normal.
So if you if you see things that that differ, this is not a definitive guide.
It's a rough red line on where to yeah, on basically on what best practices are and how
to use it and there might be other cases where people advise you otherwise.
So who joined as call in user 2?
>>> Hi, this is Mo
>> Hi, Erica.
>> Hi, Mo.
>> And, sorry, this is Howard, I just joined, also.
[Multiple voices]
>> This is Tim Bolin, I just joined.
>> Hi.
>> A lot of people of both groups are showing up and I really like that.
So, yeah. So there are obviously differences between the project and I will bring in my things
that I have learned doing the education and outreach stuff in the last two years and
and just just talking through and have have education
and outreach things as examples as well.
But...but it's a plan to draw from all of the repository, it's not that different.
So basically what Github stuff, contributions are welcome.
So you can really work with us together on the deliverables
where before it was mainly a one way thing that was done.
But now it's much more attractive and we can we want those contributions,
they make working together much more easy and help to really make the work a little bit more
smooth, at least that's what we hope that it does.
Of course, no promises here.
So first things first.
A little bit of background stuff.
What is Git?
Git is the distributed revision control system with an emphasis on speed, data integrity,
and support for distributed, non linear workflows.
And if you all are participants in W3C working groups, you know that a lot
that we do is very distributed.
Non linear.
So it seems like a good fit for us to use.
Just basically you will get into what is the version control system, basically it keeps track
of changes in the project.
So if you add a new page, if you create a page, this is recorded and then
and also the changes are reported.
Every file that's in there is reported recorded and so you get
like a nice track of how things work out.
That you can basically have on the time line and you can go back
in the version control system and get to previous versions, which is useful.
So that's one thing that we can use this for.
A repository that's basically the thing that stores all versions
and the associated metadata for the project.
So every version you create is stored in there, every dif is stored in there
and everything is stored in there as well.
Which is really neat.
And as Git is distributed, you have got basically two versions of those repositories.
One is a remote repository and the other one is a local repository.
So when you...
most version control systems like subversion or CVS - they've got central server
changes recorded.
So when your computer is not connected to the internet,
it's basically you you don't have any access to previous versions and stuff like that.
Git is different.
So every computer has a complete copy of the repository,
the online repository on the hard disk.
And so you can work without an internet connection, without your server needed to be up,
you can just copy and paste the whole repository into another folder and it will just work.
It's very versatile.
And then you can say, okay, and now I will push those changes back to the remote repository,
which in our case is on Github.
Because it's it has other capabilities as well.
So that's basically a recent feature of Git, by using Github
and having the central repository there.
Then there are commits.
Commits are basically small sets of changes that you that you submit to the repository.
They create new versions of the committed files.
And you can always add a commit message to describe what you've changed.
So if you change a for example, you could write up that you've changed the heading
and what the reasons for this are.
That makes it really easy to find who changed what, obviously.
But also if there is if there's some discussion around some wording or some change,
you can go back and actually look when was it changed
and have there been reasons for it to be changed.
So it's so it basically records that as well, and that is really neat so you don't need
to to reiterate over specific issues again and again.
So it's important to write up good commit messages.
Then there are branches.
And those are that's not an easy concept.
But basically, it means as those repositories are so independent from each other, you can even
in those repositories have independent branches.
That means you get you basically have a copy of your project
in the project that has different data.
So if I decide I want to change the design and someone else is changing the content,
we basically could both branch this, a repository, and I could work on the design
and the other person could work on the content, and we wouldn't have conflicts
and things overwriting each other and then when we're done, individually, we could bring
that branch back into the main branch, the master branch,
that has all has the final repository, basically.
So so that's incredibly useful.
And Github also encourages Github also encourages the use of branches.
They are easy to create, easy to do.
You can concentrate on one change and bring that back in to the to the main branch.
And it really helps to avoid collisions from multiple editors.
So if you got 15 minutes and you want to learn Git on the command line, which is interesting
because it's it's really a good way to get into the mood and think
about those individual terms and get the draft for that.
You can do that.
Github has tryGit resource where you can do that and basically you can really
on this page simulate your Git repository, you can Git status
and of course it's empty, that's not surprising.
And if you then a file is added, it's very good described on the top and then you get the status
and you see it's not committed yet.
It's untracked find.
And then you can add this and so on and so on.
That's basically using the command line to do that.
I can encourage you to test this out.
I just you don't need to do that now.
But I've just I'll paste the URL into the IRC, because I haven't added it
to the slides and here we go.
And, yeah, it's really interesting to get across on how it works.
It's very yeah, it's very basic, but it brings over those terms very well.
But, of course, there's no need for using the command line.
There are lots of tools that do that for you.
So this is the source tree.
It's for Mac or Windows and you basically get those nice colored graphs on the left
where you can yeah, where you can see what your branches are.
So that's pretty neat.
It works very well.
And then there are tools from Github that are a little bit more user friendly
and that are basically used for Github vernacular to speak about stuff.
So it's a little bit easier to use than using the standard stuff or using the other tools
that are not so interconnected with Github.
And that's also available for the Mac and for the PC.
For Windows PCs, of course.
Now, that's been the boring basics.
Now we're getting a little bit more hands on, on to Github.
Because when you use Github, you basically don't need to use either the command line or one
of those software tools because you can do most, if not all of it, on Github.
And especially as someone who is more in the contributor role, that is probably all you need
and most certainly all you need.
So the Github is basically a GUI for remote repositories, so you have your remote repository
and then you can you can work on that and edit that.
But it has also other features.
So it's it has also project management integrations,
so it provides an issue management solution, it has a wiki, there are milestones
in there that we can use to keep stuff on track and that's pretty powerful.
And a lot of that is actually more helpful than the source code stuff in terms
of just using it and providing it to to and providing feedback for editors of deliverables.
So one thing is every every delivery has its own repository, so, for example,
we have the WAI tutorials repository, the WAI QuickStarts repository
and the WAI WCAG quickref repository and basically the Github.com/ and then the owner
of the repository, which is W3C in that case, and then the slash
and the short time of this repository.
And as you can see, we try to prefix them with a dash because there are a lot of repositories
in the WC3 [indiscernible] and it's hard to have an overview
and sort them accordingly if we don't do that.
So yeah it's pretty straightforward so you can basically find them
on the Github.com/WC3.
There is there is a large list of of repositories, I don't know how many we have,
but it's a lot.
And you can see when they have in the last change of the one
with the last change is always on the top.
And then you can also search for it and as we have adopted the WAI naming convention,
you can just go like WAI in the [indiscernible] and then actually they should display
immediately as you can see and you get all of the WAI stuff that we're working on
or have worked on, which are a few.
So that's useful and that's how you found repository.
You probably don't think about a lot of stuff in there.
And, yeah, and we we do that and it's for each repository each delivery has its own repository.
Because it's much easier to track issues and feedback that way.
You can edit files directly in Github.
So take a look at the tutorials.
Sorry. We will have a look at the tutorials.
So we have here the source folder and the index file and this is written
in matone [[phonetic]] so so it's pretty easy to use.
Other repositories might use plain HTML and some might have code spread all over,
so it's it's a bit different from from resource to resource.
But I think you will get you will find your way around.
So what we have here is the edit this file button and so that's the pen here on the right
and you can just get in there and edit it.
If you have got edit rights, you can even commit this directly to the master branch,
which is not what I would would recommend to do because that's actually not what we should do.
And I will get back to that in a minute.
Or you can have so called pull requests and I will talk about that later.
So yeah, that's that's basically it and you can just start to type
and make your changes if you want.
And bring those in as a proposal, which is useful.
So another thing that I wanted to show is actually the main page of those repositories.
This is the tutorial help page.
It has a lot of interesting information on it, so there's there's a link
to the actual deliverable, there are the number of commits on the top,
the branches that are there.
You can create releases in Github or the editor can do that, which is useful.
You can view a list of the contributors.
And on the right, you've got that navigation that shows issues and pull requests
and wiki and some specifics and stuff.
So that's what you have everywhere and in the center, basically, you've got file lists
and directory lists of the files that are in there.
You can see how long your the last edit is has been and you will see
that that hasn't been going a lot in the tutorials lately.
And then there is actually a readme file, that readme file
that you can see here in the file list.
So it's in the root, in the root of that repository.
And it's [indiscernible] here and it's a [indiscernible] file, so you can use images and links
and texts and all of that neat stuff.
So, that's one thing.
You can switch branches here, so we have got three branches in this repository.
The master is where the work happens.
Release is where we merge in the master branch once we do another release.
And then we have the Github pages branch, which is a metric branch, if I can say that,
so I'll everything that's on the Github pages is automatically rendered HTML file automatically
rendered on the Github.io subdomain.
So if I go into the Github pages for this repository, and then you see this automated commits
because of the use of the system that creates HTML files from yeah, basically from what we
from the mocked on files [phonetic] that I've shown you before,
and that's automatically deployed to WC3.github.io/wai tutorials.
And you can browse that just like any other regular website, which is incredibly useful
for testing out stuff and showing stuff to to people while developing it.
If you have only HTML stuff to to to work on, for your deliverable,
it's just plain HTML, you can call it index.HTML, have your main branch the Github
pages branch.
And then every time you make a change, it will automatically show up on that staging server,
that's incredibly useful.
So those are the branches.
A little neat trick that we have in there is this button
on the right called quickly jump between files.
When you click on that, you can basically just put in a file name that you like.
For example, I could type simple and then I see all the files
where some kind of simple is in there.
I can do images and I get all all files that have to do with images,
like the images index file.
I can click on that and I'm directly in that file.
So when I know the file name of the directory or something like that, this really helps greatly.
And you can you can go to this file find by pressing T on every page,
so that's incredibly useful to navigate around, if only I wouldn't forget this possibility
all the time.
[Laughter].
So just pressing T and you can just type that.
Really useful.
And that's basically it's those are the the repositories.
I would come back to issues and pull requests later, as I said,
because they play a much more central role to what we're doing in WC3
and to collect feedback from you.
>> Do you have time for a quick question?
>> Sure, always.
>> How do you publish to the Github.io staging server?
>> Basically, you don't have to do anything.
You just you just make sure that you've got the Github pages branch
and then everything that's in there is automatically on the on that Github.io station server.
>> So you need to create a branch from the master?
>> Right. You'll need to create a branch from the master or what you can do,
if you only got HTML files in there, you can just create the branch Github pages
and delete the master and automatically the Github pages branch will be your your master
>> I see: Okay.
>> branch.
And then it's automatically published when you are doing that.
That's actually what I do with the quick ref.
There we go.
So what we did with the quick ref is that we get only one branch,
that is called Github pages.
>> I see, okay.
>> And that's that's easy to do in the settings.
You can and you see that there's the Github pages box in there.
That has the link to the to the resource online and also has a lot of help articles and stuff
that help you get around.
You can use pure HTML or you can use Jekyll, which is like a static site generator,
which is what I use for the quick reference at the moment.
And that basically gets passed automatically when something changes.
That's really, really neat.
>> Okay. Thank you.
>> Eric: Other questions so far?
Okay. Yeah, the questions the question that is important thinking about issues
and pull requests is to when to use what.
If I just get back to the to the tutorials, we got pull requests, a few of those.
And those are those look like this.
So they are basically there's a conversation, there are some commits attached
and there are some file changes, but in realities they are not that different
from regular issues which basically look the same and you but you don't have
that file stuff attached so you have only comments from people and then you can add labels
and I will get into that in a minute.
You can assign people to a [indiscernible] and also add milestones to this,
which is really useful if you say okay, we want to have the both issues covered
until that date, so it's more like a to do list.
That's that's really interesting and then you've got a back and forth discussion
until I have understood what you're actually wanting to give me feedback on.
Because that's that sometimes just isn't clear.
So that's it.
And then it can basically go forward.
I talked about labels a little bit, so the to the tutorials one is a little bit special.
Labels for every page.
But if we go into the quick start guide, and in those issues,
you see that there are enhancement labels on there and when you take a look
at the labels, you will see that there are basically seven labels
and those are the standard labels that Github provides, so there's bug, duplicate,
enhancement, help wanted, invalid, question and won't fix that basically you can use
to highlight specific issues and all pull requests.
Those are those issues lists and pull requests lists, they are sourcable,
they are incredibly flexible.
So so you can basically clear all filters, which I don't know why there have been filters,
and then you can go and basically say, okay, I only want
to see everything that's that's tagged with announcement and you can do that.
Oops. What have I clicked now?
You see on the right who has commented and how many comments are in there,
so you see what is the important topic for people.
That's pretty neat.
And you also can say, okay, I want to see all closed issues.
All open issues.
And as you can see, in the filters box, this is all basically text based,
which is very, very neat so you can you can if you get along with that,
you can basically just write in there and find the correct issue.
That's not so much a problem with the WC3 stuff, as we don't have
like thousands of issues at a time.
But it can be useful nonetheless, if there are, if the label had wanted
that basically asks for group input, for example, you want to first inform them
and then you can concentrate on working on those specific issues instead of thinking through,
like [indiscernible] or stuff like that, that need to be fixed that are issues,
but don't need any further input.
Yeah, if if we click on pull requests on the top, yeah, basically the filter changes
from it's open and it's pull request is pr from from it's open and it's issue,
so they are really, really closed related.
And so the question indeed is when to use what, when to use issues
and when to use pull requests.
So that's not that's actually, once you think about it, it's pretty easy.
But it's it gets some some time to get used to that, to that stuff, and when to use what.
So issues.
You should always just open an issue if you have general feedback,
if you want to discuss, like, passages or documents and you are not sure if you want
to reformulate it, but you don't have a concrete change to do on files.
Then you should use issues.
Also, if you just want to collect opinions on on different things, then you go in there
and you can open an issue and talk about that.
And just keep keep that going and that may result in something that can be integrated.
There are some there are some advice on how to write good issues.
So you should always provide a link to the page in question.
Sometimes pages are very similar, if you have a multi page deliverable at least,
so it really makes sense to point people to the specific page because, as it's easy
to get lost and it just confuses the hell out of everybody
when they're not talking about the same page.
So make sure that everyone is on the same page, basically.
Keep issues clear, concise and focused on the specific issue.
Bad: I don't like content of Page X. That does not help very much.
That's giving feedback like on this page, the wording in the introduction is unclear.
It's helping far more to to help editing this and get feedback
from the other members of the working group.
So that's really, really useful.
Try to be very specific and point people to the correct page that helps a lot.
Pull requests are for concrete text and code proposals.
So if you say, oh, I can go in there and change that in a minute, go in there
and change it in a minute.
You don't need to make an issue and discuss it discuss it.
You can just get into the file, as I showed before, and just make your changes
and send in a pull request.
That doesn't mean it will get implemented one by one like you did,
but at least you have a concrete proposal, concrete code or text proposal.
It's also useful for implementing changes that have already been discussed.
So if we got a phone conference and the group decides that a part
of the deliverable should change, you can go in there, make that change
and send in a pull request.
That is much easier than than having an issue up and then someone else is doing that.
Of course, you only should do that if you and the group have agreed
that you are responsible for this.
Then there are typos and grammar corrections.
There's usually not a lot of a lot to discuss with those.
You can always just open the file, change the code or the text and send
that in as a pull request.
And, of course, some advice for doing good pull requests as well.
So make atomar changes.
Make changes that are so as small as possible, as small as they make sense.
For example, if you get a file and there are multiple wording changes that you want to do,
you would most likely change them individually and submit them
with multiple pull requests.
So that each of them can be discussed and implemented individually.
If you go through page and basically working group has decided that they want
to change a word from one word to another because it makes more sense
or there has been a sentence that is on several pages, then you can do that all
at once and that works as well.
Because we don't expect to discuss every single change individually
because it was already discussed, so so it makes more sense like this.
So there is Github workflow and basically this catches everything we talked about.
First, when working you create a branch.
If you edit on Github and you check the check box, this is automatically done for you.
So if I go to see that, wai tutorials, if you go to wai tutorials and then to source
and then index, are and then, for example, you change this to hints,
you can then have your comment in there so that actually the second the second step.
Before the first, in one approach, so you commit changes.
We're now doing that.
Changed wording for the better.
And then you will always have the possibility to commit directly to the master branch
if you have writings, writing access and we plan we haven't discussed that in depth yet,
at least in the education and outreach working group, we basically want
to give everyone writing access as that enables you to add things
like labels and issues yourself.
So basically what you can do is just commit directly to the master branch,
but you can always check this and create a new branch
from this commit and have a pull request.
So it makes a lot of things for you that you that would be three steps,
basically combines them into one.
You can just leave that that name as it is, it doesn't matter too much.
Then you click propose file change, and then you can add labels to this file change
and assign if you want to.
You can assign me as the one who does the work because in most
of the repositories I'm I'm working with it's me anyway.
So you can assign that even and then you can have another comment
and create that pull request.
On the box you see your change in the nice format so you know, okay, that's my change and, yes,
I want to send in a pull request.
Click on create pull request and now the pull request is there.
And you will see some details.
So everyone who who now goes to the page, to the pull request page, sees that pull request,
and sees what the change is, where the change happened and that commit
and what files, what changed.
You can even edit this.
Which is important.
And I will get back to that.
And you can add comments on that.
So, for example, you could comment and say, "That's a change for the worse."
And comment that.
And you could also label that with invalid.
There we go.
Github records all of that, so you see who is adding labels and this is actually reflected live
if you would have opened that same page, it would get pushed to your browser immediately,
so it it's basically almost like a live chatting thing, if you want to,
if you are doing it at the same time.
That's pretty interesting.
And you can get notifications and stuff like that.
I will come back to that in a minute, I think.
So, yeah, that's very interesting.
And then if you if you have writing possibilities, writing access for this repository,
you can also merge the pull request in.
Which will go automatically and then basically it's in the master branch.
We don't want to do that now, but this pull request, because it's a bit ridiculous,
you could edit the file once more.
And find an example, if someone had commented and said, "That's a ridiculous change," you can go
in there and just write another suggestion, for example.
You don't need to change that specific bit.
You could change the whole sentence and stuff.
Let's go with that for a moment.
And put other idea.
And this is now actually in the yetil patch 1 branch, so I can now directly commit
to this branch because it's not in the master branch.
Or I could have a new branch and add the pull request on to the master branch.
So if there's an edit, I have both possibilities which can be used for now I want to add
to the pull request we are already dealing with, so I commit that change.
And now it changed from guidance to information, directly.
In those two comments and as we can see on the conversation page of the pull request,
we see that this this change is in there as well.
So you can basically add to this branch and play with wording until it's finished
and then you can merge merge it back into the document itself.
And I think that's a really powerful when thinking about about when thinking
about deliverables, a lot of possibilities there.
So getting back to the slides for a bit.
Yeah. Then you do open a pull request, I will just get back to the first one.
Basically the menu is to create a branch, commit changes to that, open a pull request,
then you can chat about it, discuss it and optionally add more commits,
that's what I have just shown and then you merge it together.
And that's basically how the workflow works.
And what I see now is that I'm on the end of my presentation, but I have forgotten one slide.
Obviously.
That is pretty useful, but I can't see it.
Just interesting.
Probably that got lost.
Let's see if I can recover that.
Or else I'll just do it manually.
>> Probably in a previous branch.
>> Eric: Yeah, probably.
[Laughter].
It's hard with those branches to to keep up with everything.
Oh, I didn't I didn't go down there.
Okay. That's that's interesting.
I skipped that whole section.
This happens.
So, yeah. I added stuff and that's all kinds of file types I wanted to talk more about.
So you can edit HTML, CSS/SASS, JavaScript, and of course back end stuff like PHP, Ruby,
python, and one thing that's especially supported is markdown and there is
that YAML frontmatter thing, if you take a look at the at the tutorials.
They use this on every page.
And that's the thing on the top so basically metadata that is added to individual pages.
It has this really nice view, this tabular view that's probably horrible
for screen readers to read, especially because the text representation
of it is so much nicer.
So the frontmatter is having three dashes on the top and then it's basically, yeah,
those intended lists that that help you to manage your stuff and uses the middle man
to render the HTML pages in the end and I can access all of those values from the page,
so I don't need to write my footer on every page.
But, for example, the published date is just taken from this from this file and displayed
and also the title and the navigation title.
So so that's useful.
And it has this preview functionality that I showed.
I think the tabular stuff is not that useful.
But but, of course, if you use regular markdown or HTML, that's actually rendered just
like it would be rendered on an HTML page but, of course,
without the CSS and JavaScript enabled.
And if you do fancy stuff, with with such of with such CMS or static file generator tools,
it doesn't understand that as well.
So there are limitations, but in the whole grand scheme of things,
you get a pretty nice representation of the page you are working
on in those preview [indiscernible] and just on the on the individual pages of this.
Probably a few other interesting things in here is that you've got the switches on the top.
So you can take a look at the raw file, which in this case is just a text file.
And it's probably not that not too interesting, but it's like a raw file
and on a special subdomain you can basically query that through AJAX
or stuff like that pretty easily.
So there could be some use for that.
There's blame functionality.
Blame functionality you see basically who has edited which line.
So if you've got a typo on line 20, it's clear that Chari has made the change.
And you can blame him, that's why this is called the blame view.
It's really neat to use that.
And, of course, you've got those newer and older yeah, indicators that are only color,
but but it's pretty interesting that empty roles are usually very old.
So that's the blame view and then you've got the history view.
And that's so you can see all of the comments to this one page
and so basically you can see how it evolved.
If you think about, oh, several months ago I edited something in there, and in that file
and now it's basically people are discussing it, you can just go in there and you can see all
of the and you can see all of the changes that happened,
which is which is really useful to check back.
The numbers on the right, those hexadecimal numbers, those are the the basically the commit
numbers, so every commit has has one has one of those numbers so they can reference them easily.
I see a Q. And sorry for not seeing the Q earlier.
So, Katie?
>> Though I understand more than 50% of what you are saying, I will still say that I'm confused
about and I've used Git and Github and it that's the whole point here to me,
it's incredibly complicated.
So can a simpler understanding of commit to me seems pretty clear.
You are committing this to the server.
But the pull and the what's the other one?
>> Eric: Branch?
>> Yes. The a branch I understand that you are pulling off a copy, right?
>> Eric: Yeah, basically, yes.
>> Then to put it back, you commit it.
>> Eric: You merge it.
>> Merge it.
Okay. And how is that different from a pull?
>> Eric: So good question.
So basically the work happens in branches and branches are like lanes on the highway.
If you want to do stuff on another another branch,
you basically switch the lane on the highway.
And edit in there and then when you overtook the car in front of you and have done your work,
you merge back into that lane, into the center lane in that case.
Which is quite a [indiscernible] metaphor.
But so a branch is basically the same it's the same repository,
but it is another branch of work.
A pull request is proposing that this branch is merged into the main branch.
So what you do with the pull request is that you say, "Hey, maintainer of this repository,
please merge this and put this into the master branch" or your main work branch.
It can have any name.
So that's basically how it works.
And that's the basic concept.
So you are you are singling out some piece of work and then you get that back into the mix
and you can do that as often as you want, so it can have multiple off both lanes and
and they can be merged inside of each other, which is weird, but that's a possibility.
And then they can be merged back into the main branch.
So you can have pull requests between branches of any kind.
I hope that made
>> How are the collisions then prevented?
>> Eric: The collisions are prevented, in that case,
that you can have very specific branches.
So you don't prevent the collision, but you you basically make sure
that every edit has its own playground.
Sorry. So so, if they did branches just for editing for this tutorial, for example,
or for this specific feature, or just for the design.
Then everything gets committed to this branch and, of course,
there could be conflict in there.
But it's it's much less likely that when you merge it back that someone else did work
on the same branch as you did.
>> Eric, would it be safe to say that the the most granular level
of the changes is a line by line change?
So in that previous example when you had, when you changed the information from, I don't know,
yeah, those three things you said worst, you know, better and worse and to try this,
was it only that word that was going to get merged back in or was it the entire line of code
that that word belongs to that goes back into the merge?
>> Eric: As far as I know, and I'm not really sure, the whole line gets merged.
But it has the some algorithms that say, okay, this is the thing that has changed.
So if if something else in the line has changed as well.
It won't get overwritten.
>> So it will be say, "Hey, listen everybody, we've got to stop for a second,
we've got a collision possibility here because two people tried
to edit the exact same line and different merges;" is that right?
>> Eric: Usually it works out well.
Sometimes there are collisions and you need to basically put them down
and edit it back together manually, but I don't think that's that's something
that should happen often and if it happens, it shouldn't be something you
as contributors worry about.
I think we as editors are there to support you with that.
>> Okay.
>> Eric: Howard?
>> Yeah, I had a question, Eric.
I was, you know, we talked about at the last meeting, for instance,
updating the luminosity or color contrast ratio tool listing, tool resource.
Now, let's say I wanted to work on that.
And I could I have would I pull that into Github, let's say, you know, I wanted to start working
on it and suggest changes and have other people make changes.
Is there I'm sure I assume there's an easy way to just pull that into Github
and then work on it from there.
Can you tell me how to do that?
>> Eric: Yeah.
So for the people from WCAG working group, I just we had the discussion
in educational outreach on Friday because we are preparing both quick start guides
that basically helps people to on ramp and track the accessibility,
telling them what they need to do, basically first baby steps into stuff
and we reference the list of color of of color ratio, contrast ratio tools that is
in the in the techniques.
And some people noted that it's outdated and now what to do about that.
So I get into the WCAG repository, and then we take a look around.
So the WCAG group repository basically it's one huge collection of X amount
of files that, yeah, that one could edit.
So if I get in there and into techniques and then into I think UA notes.
Um ... no.
I don't think that's it.
And then you get basically confused and go back
and [Laughter] and don't do anything.
So there are the techniques and then I I have forgotten which one that was.
I think it's CSS, it's a general one.
I think general.
Yeah. And then you can go into those XML files.
So I would just go into this one, for example, there you've got all of the descriptions
and stuff in there and it's a very [indiscernible] XML formats that some people understand.
You've got related techniques and in the in the one with the color contrast,
[indiscernible], contrast ratio ...
ratio ... contrast ratio, that's this one.
>> And I can send you the URL, the page that I'm specifically talking about.
The tools page, would that be helpful?
>> Eric: Yeah.
>> Instead of looking for it, I will put that in IRC.
>> Eric: Awesome.
Right. There we go.
It's an understanding yeah, understanding even more complex off the document,
so so that's why I wouldn't advise you to edit understanding correct
to directly it's visual audio contrast, understanding,
then you've got the visual audio contrast and [indiscernible].
So it should be somewhere in there.
Yes, here are the resources.
So so that's all you can find us and then it's got basically like age ref things
where you could make changes now.
So you could theoretically edit this file.
>> I would want to would I want to branch it first before I did anything?
You know, I'm just
>> Eric: You could do that in one step, so if you got on the button create a new branch
and probably it says create a new fork, which is the same thing, don't get confused.
>> Oh, okay.
I'm confused.
[Laughter].
>> Eric: So if you don't have writing access to [indiscernible] it will fork it.
Forking is the same thing as branching.
Only that it is in your account and not in the account of and not in the main
>> I see.
>> Eric: In the main repository.
So basically, if you download, clone the repository on to your computer, you are forking
that as well, but no one would say would know it's like that.
So you can do that in one thing and get a pull request and you could change them out.
What you also can do, that probably makes a bit more sense in this case, is to just go
to issues and create a new issue.
And write your suggestions in there.
Then people can comment on it, can contribute other ideas to that,
can link other resources to it.
And then in the end, the editors can say, okay, this is the list of resources we want to add
to that technique, to that understanding document, and they can basically then compile the
list themselves and put it in there.
So because it's a much more open process, I think that's useful.
If you've got a concrete tool on that list that is broken, for example,
or the URL is not resolving anymore, then you would go in there and just deleting
that link and commenting that this is not working anymore.
So you
>> Put in a new link or whatever, yeah.
>> Eric: You could also put in a new link and then people could discuss the pull request,
as I said.
It's not that clear cut when to use the pull request or when to use an issue.
Basically for gathering of information, I would prefer an issue.
But in that case, it's basically 50/50, what to use and I think the editors of WCAG are fine
with having having directly a pull request in there.
>> Okay.
>> Eric: So, yeah, that's that basically is the approach.
To find that, I will put the link to the file into IRC
so you can just go there and have a look.
If you want to.
Yeah, that's that's how she used the the XML files and to get through the WCAG repository,
which is huge and very confusing, even for me, and very XML, so so I have heard
that techniques that we're thinking about moving the techniques to a different system
so we can edit them more easily, but I don't know if that will also apply
to the understanding document.
>> Okay. That helped a lot.
Thanks.
>> Eric: Thank you, Howard.
So just getting back to the slides.
Those were all of the file types, so you saw XML is in there as well and you got
that nice highlighting fun stuff, it's really useful.
I have talked about issues and I have talked about pull requests.
And as you see, those are the slides that I skipped over.
I didn't do it in the in the order I wanted, actually, [Laughter], so ...
but we have talked about everything that is interesting.
When you are doing pull requests or issues, you have some nice possibilities
to reference people and/or issues and/or commits.
So when you're typing the username, it's basically like an "@" reply on Twitter
and that person gets a ping and can can react to your comment or your pull request.
That's really neat.
If you write #123, it will automatically link to issue 123 from this.
So you don't need to search for the URL.
If you want to reference a specific commit, I have talked about the commit hash.
For example, 6F8BDDCO11 on one, C011.
Those are every commit has one of those and you can also, if you go into the history
of that file, you can copy and paste that from the right and if you look
at the main WCAG repository thing, it's in there as well.
So so easy to access and then you can say oh, I moved that really, I don't really think
that this commit is the right thing.
So if we go back to to the issue I've created and in the tutorials, the pull request
that I have created, then I have the other idea and on the right you'll see
that the hash is there as well, also.
Although it's not really easy to read.
But then you could say at the person you want to reference, I thought the change
in then copying or pasting in the commit hash was better.
Then you can comment.
And so this links to the profile and this links to the to the change,
the change from guidance to hints.
And that's very useful to speak about stuff and get this out correctly.
So that's something that you can do.
Another thing that you can do is that those those comment boxes everywhere are supporting
markdown, as it says here.
So basically you've got other things as well that you can do.
For example, you can have bold and italic things in there, you can have links in there
that don't that don't need to be just plain text links.
Of course, plain text URLs work as well and they get converted to real anchors.
Then you can use lists.
So if you've got 1, 2, 3, or a star or a bullet point or dash as a bullet point,
those will be converted into HTML.
It's super useful to write stuff out, so if you're creating if you're creating your commits,
use that to structure your commits.
It can be really useful.
If you look into images, you can, of course, reference images
from there, which is nice as well.
You can use headings, if you've got something that's really long
and probably then it's not an issue, but more like a like a long text,
so you can use all six headings, structures, if you would like to.
And you can use the the angle bracket to have a quote in there as well.
So, for example, that would be useful if you discussed something in in the meeting
and then this gets minuted and then you want to reference those minutes for what you're doing,
you can copy that over and quote that, really useful.
It has code support, which is probably not too surprising.
When we consider that it's it's basically the code [indiscernible] platform.
So so it uses [indiscernible] like this to mark up end line code and triple [indiscernible]
if it's like a block of code and if you want you can also have the triple back ticks on the top
and immediately follow it by the language that is used and then it has
like those need syntax highlighting stuff, are which is useful.
That's why I try to use that as often as possible.
And then there are some extras, you can have checklists in there
with complete and incomplete items.
It's basically a list and then you've got in square brackets the the [indiscernible] space
on x that marks the completed stuff and in your repository you can check and uncheck that
and it gets automatically saved, which is pretty nice.
And, of course, there are some emojis that you can use because what is a modern system
without any emojis.
And that you can use to give more specific feedback.
I think it's very neat that we can be so structured on things.
If you've got questions left, I take them now.
And I or else I would pull up an example I've yeah prepared, in air quotes,
but I have made some changes to the tutorials, which come from issues
and I can basically fix those issues now and I would like to show that to you
as the next step in this basically the last thing we do today.
So any questions or is everyone still only at 50% of understanding?
>> I'm at 55.
[Laughter].
>> Eric: Oh, that's very good.
>> Eric, it seems like a lot of the people that I was speaking to,
at least on the mobile task force, are using an editor and, you know,
and going that way rather than directly into Github itself.
Do you personally find yourself using the the editor, the interface,
the Github interface itself rather than, you know, a local editor?
>> Eric: Well, for me it depends.
When I'm writing text, I'm usually use my local editor
because I think it's much more convenient.
And I like to think through stuff and also with the with the tutorials, for example,
those need to be regenerated whenever I make a change and I can have that run locally,
so I can see it all the time, how stuff changes, that's more convenient for me.
But basically, it depends on the change.
If it's a quick change I use the the Github
>> So are you using SourceTree, also?
>> Eric: I actually use Tower for Mac, it's a commercial tool.
But they are working all the same.
They are not too much differences between them.
It's more the user interface stuff.
But, yeah, it's not that different, once you got the nomenclature right
and know what you are talking about there, they're pretty similar.
>> Yeah, the because there are a few questions that of course SourceTree,
just to make sure that, you know, if you have a fork going on and you're trying
to do a pull request, how do you relate that fork to the master,
the original master in that kind of thing?
It sounds like a 2.0 tutorial perhaps.
>> Eric: Yeah.
So the pull request thing is something that is basically a Github thing.
So you can't do that from external tools apart from the Github tools that they provide.
So if you want to use [indiscernible] for branching, not for branching
but for merging things back as a pull request and just and request a pull in the interface
for on Github, you basically have to use Github and do that online.
So I can show you how that works.
So if we go into the tutorials.
Or I'll just go to the quick start tips because it's not not such a large tutorial.
Such a large repository.
So it's easier.
So we've got 11 branches in there.
And most are most are put in there how it should be.
So so if if I had changes now and wanted to pull that into it, I can use the the compare,
review and create pull request button.
And then you see you can say "I want the base branch."
That's basically the master branch.
And then you compare, for example, the you have to attach one,
which probably is way out of date.
There's nothing to compare because I've already put that in.
But if I fork this to my own own thing and make a change, for example,
deleting things in there, just for
>> Yeah, I understand you.
>> Eric: And then the pull request so I cannot commit directly to my master branch.
Because that's local in my thing and then it doesn't work.
That's interesting.
Oh, yeah, okay.
So um ... that worked actually worked out.
Just a small hiccup.
And then then now I could I could do the pull request and the base is WC3 repository
and this is my repository.
And then I see that I'm able to create a pull request and that works
like like it usually would work.
So you click on create a pull request and then you can add your labels and your comment
and your stuff like that.
>> Okay. So on the left hand side, when you say your base, that's the one that you're going
to be comparing everything else to?
>> Eric: Yes.
So the base is the repository and branch, that that the things are committed to.
And yeah, that's confusing.
And the the thing you are currently working on, that those are called hatch branch
and hatch fork, in that case.
>> So theoretically, I could actually I could merge a master branch into my
like if I changed something in my master branch, on the master branch
and then I had my own little branch going on, I could actually put
that into my branch using this tool and the base would be my branch
and the other one would be the master branch, right?
>> Eric: Right.
So what we do with the tutorial, we have that release branch and into
that branch we always once we do a release, we put our master branch, we pull that in there,
that's not a pull request, per se, because we can do it just straightforward
and commit that to that.
And just merge them.
But yeah, you can do that.
Because when you think about about problems or stuff and you're working on your version
of it on your fork, so to speak, of that, you are the one who who makes progress
and then probably the source repository makes progress as well and you're out of sync.
And for those things that you haven't worked on, you probably want to pull in the changes
of that master branch so, yeah, you can branch as much as you like.
Basically.
And from which sides basically that you want.
It's a pretty it's a pretty it's a concept that's really, really powerful, but as we know,
that comes with a lot of responsibility, so, yeah, it's it's there's a lot going on.
So any other questions?
Doesn't sound like it.
Okay. Then I just I'll get this up.
So for the ah clicked the wrong icon.
So for the tutorials, we've got this this bug number 303 that was reported
as something that does not work.
And we also got another related bug down here that is this one, 85,
that that also was was reported.
And I have addressed it now.
So I will just switch to my to Tower, I'm sharing two applications,
how does that look like for you?
>> It's fine.
>> All we see is Tower, right?
>> Eric: So if I switch to Safari, you see Safari.
>> We see that.
>> Eric: Oh, that's interesting, that's useful.
So that's Tower and here are the changes in the file.
And those as I said, those things basically look the same everywhere and you don't need
to to think about those about those things.
You can always have the history and see your your branches and here, of course,
are our our branches that are on the top, so if I would change now
to the yetil patch 1 branch, I could do that.
I could check that out on my computer and work on this idea that I will most likely not use.
But but, yeah, there are a few things in there and then you'll see
when things are would collide, basically you've got more branches
and they are then merged into each other and it's usually no problem and the nice thing
with this, that's the particular nice one, and and the nice thing with with this client is
that it's very colorful thing that that's the thing that I'm enjoying the most out of this,
especially if it works like that.
[Laughter].
You got you've got like really interesting stuff so that happens when you use
like really, really microscopic changes and send in pull requests
and then I merge them in, you make me very happy because my client is getting so,
so colorful.
So so but what I've done here is basically I've changed those things
and have some some changes in there.
I will now mark them all as and stage them all, that's basically
>> Eric?
>> Eric: Yes.
>> Excuse me, this is Katie, one second.
What is the comparable tool to Tower for Windows?
Is that Sparkle?
>> Eric: I don't know about Sparkle, SourceTree is working very well and the Github
for Windows is working well as well.
>> I use Github for Windows, but I don't think that's it gets messed up with Windows 8
and it bothers me, so maybe I need to use SourceTree.
>> Eric: Yeah, then you should take a look at SourceTree.
>> Yes, SourceTree is what everybody on the mobile task force is using.
I just moved over to it.
I was on the Github
>> Okay, okay.
>> Eric: Yeah, SourceTree has all of the nitty gritty of Git built in there,
so the Github stuff, at least they use the Github wording and stuff.
But they are pretty much dumbed down and don't expose like the real power of Git.
So, yeah. That's that's so SourceTree is quite good for what it is.
So I've now staged that.
So that staging in that context means that I mark it that I want to commit it.
If I would have like multiple files, I could choose to only commit a few of them.
And even here on the right side, in this line, I can only stage a chunk of edits.
And then only this will be committed.
For example, if I had reworked a text and I want to have multiple commits out of that,
because there were separate issues, I could do that.
But that's not too relevant in this context.
What I can do now is having my commit message, it's the same thing
that you can do on Github itself.
Fix dropdown bugss.
You want to be at least a bit precise and then I can go and write fixes,
issue #185 and fixes #303.
And what's happened now is when I commit that, nothing happens because this is now only
on my computer and I will check back to the Safari once I would push that to the remote server.
So that's the other thing.
When you have a remote repository and edit the stuff on your computer,
you basically need to pull the changes in and that's very confusing with the pull requests
and I'm so sorry, but that's how they named stuff.
But basically you pull stuff down to your computer and then you need
to push it up into the cloud.
And what we're doing now is we will push this branch that has the has the changes in there
and click on push and we want to push that to this branch, to the master branch and what happens
in Safari, instantly, once we do that, is this this issue that was referenced
in there is automatically closed because I have fixed our fixes #185.
It automatically detects that and closes those box, which of course is very useful
and you get on the bottom you get the reference to to the commit, so and you get the links
to the other issue, as well.
And you can basically look at how what has changed and stuff like that.
That's really useful, makes it really easy to work with that Github stuff.
And with the issues on Github.
So that's basically how to fix things using Git and Github.
And I don't think I have a lot more and it's going on for quite some time.
So any questions, closing questions?
>> I just want to thank you, Eric, for putting the time in
and giving us this intro into Github.
I think it's been very useful and it gives you a springboard to continue on with.
Thank you for your efforts and your hard work in setting up for this.
Of.
>> Eric: That's not a question, but thank you.
[Laughter].
>> I have a question, but it's not about Github really.
Do you say before that the [indiscernible] will be moved
to another system, to another repository?
>> Eric: Yeah, so that's pretty much in discussion in WCAG.
So we WCAG working group thinks about some possibilities and we can follow up on that off line
and I can point you to the relevant discussion.
There's nothing definitive on there and they will stay in that format
as they are for quite some time.
>> Okay. Thank you.
And thank you for your presentation.
>> Eric: Thank you.
Okay.
>> Thanks, Eric, it was really helpful.
>> Eric: I hope so.
I hope so.
I hope you all now understand about 56% of [Laughter] of what's going on in Github.
That is more than I do understand.
So [Laughter].
It's it's very interesting and it's very there's a lot of stuff in there.
And the just getting practice with those those issues and things that have the most to get
to get to grips with this.
So, yeah, I think it's it will hopefully help us to to work a little bit more efficient
and directly on the deliverables because I think that will help a lot.
>> Thank you, Eric, appreciate it.
>> Eric: Thank you very much for attending this.
I will see if I get the video out of and off the WebEx somehow and post it on YouTube
or something like that for the people who couldn't attend
because I think that's really, really useful.
If you have got follow up questions, I'll keep the Github IRC channel
up for the next few days at least.
Probably we will stay in there forever and just approach me and ask questions
and we can we can see how to how to move along.
Thank you very much.
[End of webinar].