NRE Labs Labs and Latte, 26 Mar 2021

Previous Meeting

Next Meeting

⏯

youtube image

►

From YouTube: Labs & Latte: Introduction to Git Part 6 - Proposing a Change To Another Project

Description

In this edition of Labs and Latte, Matt dives into Part 6 of our "Introduction to Git" series, which covers our ability to work with remote Git repositories, such as those hosted by GitHub.

If you want to follow along, you can play with this lesson right now at https://go.nrelabs.io/labs/?lessonSlug=git-version-control&lessonStage=5

EDITORS NOTE: Sorry for the crappy video quality, I didn't have access all of my usual equipment for this video.

Introduction to Git Series:
- Part 1 - https://www.youtube.com/watch?v=YAXWxA4x8vs
- Part 2 - https://www.youtube.com/watch?v=b203WRT_hIg
- Part 3 - https://www.youtube.com/watch?v=mOj7kCfu7TY
- Part 4 - https://www.youtube.com/watch?v=qOmQzUR5t0E
- Part 5 - https://www.youtube.com/watch?v=Bqtk0wpgl4A
- Part 6 - https://www.youtube.com/watch?v=TsTlwF2IgwQ

A

Hello and welcome to labs and latte. This is a show where we dive into the energy labs curriculum while sipping on our favorite bean-based beverages and I'm cheating a little bit today. I already had my coffee and I was going to try to keep it around uh for this video, but I just drank it too fast, so I'm I'm having some emergency for vitamin c.

A

That's! Okay, though.

A

Let's get into today's lesson, so this is going to be uh probably the last chapter in the git lesson, at least for a while, because it covers the one thing that I've wanted to cover for a while, which is the question everybody has uh in in at least in this, in the space where I work.

A

Typically, how can I contribute to other open source projects with git we've kind of touched on some of the some of the details of what you might need to do that, but in this section we're actually going to tackle that directly because there's some stuff we haven't covered yet um so, let's see let's get into it. So if you'd like to follow along, I encourage you to do so. The link will be in the description of this video.

A

This is the sixth chapter for the get lesson so we've been kind of at this for a while, um but uh gets kind of a complex topic. So that's not actually that weird. So the thing to cover in the in today's chapter is a specific workflow that um isn't always used, but it's a fairly popular one um I'll caveat this with saying: if you're, using something other than like github or git lab, then you might have a different workflow early on.

A

In my software career, I used a piece of software called garrett, and the workflow is significantly different than what I'm about to explain. But this workflow is is extremely popular and I think part of that is because of github and gitlab. So if your target is something like that, like a project, that's hosted on one of those sites, this is going to be really uh handy for you. I it goes by a bunch of different names, but I like to call this the fork and pull workflow.

A

Basically, the idea is really simple: you have a repository um out there that you don't own up until now, we've been working with repositories that we do own repositories that we create and that we pull from that. We push to everything everything's fine, because we own it. So we have all the permissions we need, but in an open source project. That's almost never the case right. um Only a few people actually typically have write access, meaning they have the ability to push directly to the repository in question in an open source project, especially large ones.

A

So, typically, what they use is a workflow that instead forces people to make copies of that repository, make changes there and then submit something called a pull request, which is really it's kind of, as it sounds you're requesting that the changes that you've made in your own copy get pulled back into the main or upstream uh repository for that project and in so doing, you've contributed to it, and so we call that the fork- and I call that the fork and pull workflow um fork by the way I want to bring this up- and I write- I wrote this in the lesson.

A

But I'll do a quick aside on this forking has kind of a weird negative connotation, because there are situations where, um where somebody you know, somebody comes across a software project and they want to make some changes or they propose changes and the project owners either are unresponsive or unwilling to accept those changes.

A

A lot of open source licenses will allow you to simply say: look I'm going to make a effectively a hard fork right here, wherever the project is and there's a long history of projects doing this and where you say, look, I'm going to take my own version of the project in a different direction, maybe under a different name that happens, you know pretty pretty often it's a it's a fairly fragmenting action like obviously now you have two communities and they got to figure out sort of which side they're on so it has a little bit of a negative connotation in this case, however, the word forking means none of that.

A

That's not at all what we're talking about when we talk about forking in this case, what we're actually talking about is a fairly common, somewhat good thing when we make a fork of a repository, what we're intending on doing is using it as a temporary holding place for our changes, we're not taking the project in a new direction. What we're doing is we're saying, let's make a copy of this repository, called a fork or a soft fork.

A

If you want to call it that, and what we'll do is we'll make our changes there, because we own that copy and that fork we'll make the changes there and then we'll submit a pull request to say: hey, you know, sort of upstream maintainers the people who actually run the real project. The original.

A

Please pull the changes out of my fork into yours and in so doing incorporating my changes into your project. That's basically the workflow so fork and pull okay. So, let's get into it. This is, uh as I mentioned. This is the uh the lesson in question and, like I said before, if you want to follow along- and I encourage you to do so- the description will contain the link to do that.

A

So again, the the name of the game here is to contribute to a repository that already exists. So if we go to the remote tab which we've looked at before you can hit, explore and make sure you're signed in by the way, if you don't see, this make sure you sign in the credentials are jane, is the username and then password1 is the password you'll notice? There's a repository here that we don't that we haven't talked about yet under the initech username.

A

So this is a totally separate username on our git remote and if this was github, this would appear really identically. um You know, for instance, ansible. It would be. I think they have ansible slash ansible. So that's a a whole organization dedicated to managing that project. But in any case this is a project that we don't own. It's not under our username.

A

We don't have we're not on the sort of in the organization that this belongs to we're, not a part of its team, we're just some github user um that sees this project, but we'd still like to contribute to it, and so we need to follow the workflow that I described just a few minutes ago.

A

So the first thing we want to do is you can scroll down. I have screenshots here to follow this. um I think the the the lesson walks us through changing one of the network configurations, and so you can see this. This particular repository has a bunch of network configurations in it, so vqfx1.txt a bunch of junos configs in there. So, let's, uh let's see if we can change this using the fork and pull method that we need to use since we don't own the project and we can't just commit to it directly.

A

So the thing to do here- and this is one of the reasons I like this software- that I'm using in this lesson called get t- is it it looks very similar to github.

A

So if you're, if you're um I, if your idea of contributing to an open source project is in and that project is on github, this will work really nicely for you, because it's very similar, it's not exactly close, it's not exactly the same, but it's pretty close, so click fork and again this is actually totally normal for what we're trying to do, because our intention is to upstream the changes that we're making.

A

So we click fork repository everything everything the default is fine. We don't need to change the name or anything like that. We just click fork repository and now you can see a few things have changed again. This is very similar to how github does things and even gitlab, to some extent.

A

So the first thing you can see that's a big giveaway is that there's a huge fork, icon right here in the top left that indicates that you're working on a fork and then, of course, you see, the name of the repository is actually under our username, now jane slash network configs and then there's a nice little notice under here that says hey this was originally forked from in attack network and fix just to let everybody know that that's where that came from.

A

But the cool thing is. This is effectively our own copy of the original project, but changes we make here uh uh un. Unlike the original project changes we make here, uh we are allowed to do that. We have this is under our username, and so we have the ability to make commits and push branches to this repository.

A

So that is what we will do now now that we have basically what we had in the last lesson or last chapter, a repository that we own we can commit to it. Just like we would any other repository.

A

So for this chapter we have a new command called git clone. Now, in previous chapters we already had a repository locally and we actually pushed it to our remote. In this case we actually have the opposite. We don't actually have the repository yet locally. We don't even have the directory for it. So what we want to do is we want to basically download the existing repository onto our machine and that's what git clone does.

A

So, if you see something different here, just make sure the ssh key from the last section is installed. That's pretty important, but you should. You should be able to see something like this pretty immediately. Basically, what it's doing is it's just downloading that whole repository, so that now we have a network configs directory that we can get into, and then you can do a git log just to see that there's an existing commit there.

A

So this is exactly what we saw in the upstream project and then, since we made a fork of it, then we made a copy of it. We didn't make any changes, so we see exactly the same thing. So this commit was from the original repository, which is why you can see it's from nre admin, which is obviously not us.

A

We are jane, okay, so the other thing that I want to bring up- and this is something I explored in the last chapter- but you can see that git clone actually already sets up a remote for us. So that's something else we don't have to do when we use git clone. Is it already sets up a remote under the name origin using the url that we cloned from so get at remote colon jane again, our username slash network configs dot get so. This is basically the orig the origin remote for our own fork.

A

So anytime we push or pull from origin it's going to be pulling and pushing from that repository, which is exactly what we want. Okay. So let's make a quick change. I'm going to go through this quickly, because this is something we've done in previous chapters. I don't want to belabor this point. We've checked out a branch before we're just going to make a quick change to the as number in vqfx1.txt and then we'll do a display, git diff, just to show it in action. Obviously this is just an example.

A

You can use whatever change you want. If you want to change something else feel free to do that. You can see the diff here and again. This is pretty straightforward. We've done this before we've added it to staging, so the change that we made is now in staging there. We go green text and then we'll commit git, commit sign off and then message updated as number for vkfx1, okay cool.

A

So now we could push to our origin.

A

Remote and you can see, we have the permission to do that because it's our repository, um it doesn't matter that it's a fork, um it just matters that it's underneath our username and therefore we have access to it cool. So, let's go back to the remote tab and you can see we're still here at the home screen. So if you're not there go into your fork, jane slash network configs, so this is our fork.

A

The button that should become available now is this button called new pull request, so go ahead and click that there's actually quite a few places where you could go get to this screen. You might have noticed on the last output. There was actually a helpful link that we could go to. You can click that github does the same thing by the way. I don't know if gitlab does, but I imagine they do it. It seems like a lot of sort of git services have started to do this kind of helpful thing.

A

So if it detects that you're pushing a new branch, basically it'll just give you a helpful link that you can just click and it'll. Take you right to the new pull request screen, but in any case, knowing where the button is is also helpful. So here is important, because what we're doing here is we're comparing the two branches right now, um innotech, master and jane master are identical because we created a new branch which is well. I mentioned this in the lesson.

A

I would actually recommend doing that, even though we're in a different fork- and you don't have to you- could make commits against your own forks master as opposed to creating a branch first.

A

The reason I do it this way is because honestly, like a lot of times, I'm making multiple changes to an open source project, multiple pull requests in flight, and it's really helpful to have different branches on my own fork to keep that work sort of separate, as opposed to trying to like figure out how to order it and do certain changes after certain changes like I don't want to mess with any of that.

A

I just want to make changes in their own branches, and so I usually create a branch first, which is what we did in this lesson. So what?

A

In this case, because we did that we want to make sure we're comparing the right branches, we obviously still want to merge into the master branch of innotex repository the upstream repository, but the source, basically, where we made our changes, is on not only our fork but also the branch that we made on that fork so make sure you're, comparing the two branches properly uh github works, the same way by the way. This is very similar to github and then click new pull request.

A

It'll, give you a little bit of a form here feel free to put whatever you have in here. um I'm going to bring this up at the end of this video, but there's there's, there's definitely rules for various open source projects as to what you should have here. Most projects, don't like you to just like leave this blank. They like to hear at least a little bit of your intention and what kind of things you have left to do.

A

If anything things like that, but we'll get there for now, because it's just an example we'll just leave it blank so create pull request and there we go. We now have our own pull request that basically, is a a point of communication between us and the upstream project. Maintainers you'll notice, also that the pull request is actually underneath the upstream project, so in a text network configs, as opposed to being under our fork- that wouldn't make sense right.

A

The fork is where our changes are, but the discussion and the intention is that this gets merged into the master branch of the upstream project, as it's declared here basically jane says: jane wants to merge one commit from the fork, our fork and our branch on that fork into the master branch of this upstream project. So it's very obvious to everybody what's being uh suggested here now. This is the creation of the pull request. um One thing I'll note here: I don't think I mentioned this too much in the lesson, but very rarely is this.

A

The end of it um almost always uh you'll get a code review. um I obviously this totally depends on the platform and definitely depends greatly on the project. What the process is for that. um So definitely um I'll mention this a little bit um after after this, but um uh more than likely you're going to want to continue to make changes to this pull request. It's very unless it's a very simple, straightforward, easy to review change.

A

It's almost certain that you're not going to just push one commit and then be done more than likely somebody will say hey. Can you change this because of other? You know some reason that you didn't really know about, so just be aware of that. That's not actually that weird and and definitely don't take it personally. It's just the project maintainers trying to make sure that the the rules of the project or the the agreed-upon sort of procedures of the project are followed um and so just be prepared to make more commits onto that same branch.

A

The way that this works uh in this in get t here as well as github and gitlab all of them work this way. If you need to make additional changes, just make more commits on your branch in your fork and um the software will figure that out and make and and automatically update the pull requests.

A

So you really only need to open the pull request once and then any commits you can you add on to that branch before it's merged, um keep getting updated into the pull request, which is very handy so just fyi on that last thing I want to cover is how to stay up to date with upstream changes, because that happens a lot as well, especially on very popular open source projects, very large open source projects, their master branch is busy and there are people who are dedicated to just merging code into the master branch and making sure that it's done properly.

A

So um what will happen is if you're, not careful, especially if you, especially if your pr is open for any length of time, um your pull request or your branch rather will become out of date in a way that can't automatically be caught up. We've already covered merge conflicts in a previous section. You can kind of think of it like that.

A

Basically, if we were to try to merge this branch into the master branch, there would be a merge conflict, because maybe somebody else made a change to the as number and it got merged before our change did. This is again exactly something we covered in the last few sections, so that can happen with this as well, because- and it's even more likely frankly, because more people for really popular open source projects are contributing all the time.

A

So the question is: how do you stay up to date with those upstream changes, even though they're two separate remotes, because that can get kind of confusing a little bit of a mystery?

A

So what I like to do- and this is this- is where you can kind of define your own workflow, but I found very useful, something I found very useful is to add a second remote called upstream, and you point that remote at the upstream project, or really the in our case the initech copy, the original copy, rather of this repository, so the get remote ad.

A

This is something we've done before we add, but instead of using the name origin which is taken- and of course the convention is that that's the one we have right access to upstream kind of indicates: hey. You don't have right access to this, but you do have read access to this, so you can pull changes as they come in from that remote and then incorporate those into your local branch, which is super useful.

A

So let's run these two commands. You can see now that we have so. I ran this just quickly, get remote add-up stream and then the url of the original repository. Then you can see git remote v, which shows us the output of all of our remotes. We still have our origin in there, but now we have a new upstream in here as well.

A

So what we can do next is we do get um check out master and actually.

A

I was gonna figure out if I can simulate this, but that's okay. Let's just imagine that a change came down. This is the same workflow that you would want to apply, so you check out your master branch and then what you do is you say: git pull upstream, not origin, upstream master. What we're doing here is we're, saying: look.

A

The upstream master branch is what we want to merge into, so we want to make sure those changes are pulled here locally to my master branch so that it's identical to what I'm going to try to merge my branch into as part of my pr. So we'll run that if there were new changes they would get pulled down here. There happened to not be any changes, but if there were they would get pulled down and then the next thing we want to do is pretty straightforward.

A

Basically, what we want to do is recheck out our our change branch, so change as number.

A

We will then uh do the the merge operation that we would that we did in the previous section where we wanted to catch our own repository up with our own master branch, same exact, workflow, master change as number oops.

A

There we go and again if there were changes to the master branch that that had been pulled down in the previous command or previous two commands, then merging them into into change. As number would happen here, um if there are merge conflicts which there would be um because of this, this is where you would deal with them.

A

So the the reason we like to do it this way is so that we can take um take on the the responsibility of making sure that our changes sort of deconflict with those uh the changes that happen before us- and this is what most maintainers would like us to do is- is make sure that we, if there are perceived conflicts or future conflicts in merging, we want to deal with those conflicts here on our own branch. That way merging the pull. Requests can happen very simply so again.

A

We we didn't receive any changes from master in this step, but if we had this is where that would happen, and this is where any merge conflicts would be dealt with. So, finally, we would say: git push origin change as number again we're pushing to origin this time we're pushing to our fork. We can't push to the upstream.

A

We can only pull from that, but what we've done is we've remedied the merge conflicts in our own local branch, and so what we want to do is push that remedy to the change is number branch and, like I said when you do, that, the pull request will automatically get updated with those changes, and you can see we've kind of uh received that as well.

A

So there we go and we now have uh our pull request with an updated master branch, and uh you know all of those things are straightforward. Now, like I said this is likely not to be the last step. More than likely the the project maintainer is going to leave some comments. You hopefully constructive, where you can make improvements and get it to the point where they're comfortable merging it. That is not weird, that's a very normal part of the process.

A

The other thing I'll mention just sort of in closing here um this. These sort of technical steps of learning how to work with git are important. Git itself is clearly a barrier to entry for a lot of people and it and and and it should be- um uh it's um it's a good skill to have clearly um it's. It's definitely part of uh the bar for contributing to open source projects, but it is sort of, in my opinion, sort of the bare minimum, and it's definitely not everything that you'll need to know.

A

um A lot of what I've found contributing to open source is actually not super technical um in terms of like learning what it takes to contribute. um It's it's required this part's required, but also there's a whole bunch of other things that I can't possibly cover. Certainly not in this lesson on what it'll take to contribute to an open source project. One of the reasons is: every open source project is different. It has its own processes. It has its own culture. Git, of course, is is is a fairly robust and flexible tool.

A

There's a bunch of different ways to use git a bunch of different ways to use github, and so just because you know one way doesn't mean that way is compatible with the way that that project likes to do things so take this skill set not as sort of the the end-all be-all of everything that you need to know, but more of like the very basic building blocks, definitely take this and but go a step further and say. Okay, I have a project in mind. I really want to contribute to it.

A

Go learn about how they receive contributions specifically because it'll go well beyond what I've covered here. Maybe look at some of the existing contributions and how those went find a really good find one of the more common contributors, because those these platforms like github, allow you to see that figure out what they do on the project. What kind of things they they do in their pull requests? What kind of descriptions are in place read the documentation for the for the for the for that project.

A

um If there's a discord or a slack channel for the project pop in and say, hey, I'm new to contributing what should I know what kind of things should I make sure I account for in my pull requests so that um it fits with the the culture and the process. The project do all of that homework and I think what you'll find is doing that work in advance will make your contribution so much smoother of an experience, um and I think that that can't be stated enough frankly, so that is for now.

A

I believe um the end of the git lesson. I might contribute um any uh some further chapters in the future, but for now I think that covers um a lot of the the really the really basic stuff. um So until next time I will see you out there on the.

A

A