047 Tutorial on forking JCB snippets so you can share your snippets with the rest of the Community

FORKING JCB SNIPPETS SO YOU CAN SHARE YOUR SNIPPETS WITH THE REST OF THE COMMUNITY

Now that we've given you a general overview of how things work in the new Snippet Manager, I would like you to take the next step and that is 00:00:11 showing you how to take shared snippets and share them.

Fork JCB Community Snippets On GitHub, Export Snippets You like To Contribute, Make Pull Request

There are two things that should be done. One is you need to fork the JCB community Snippets on GitHub so you'll need a GitHub account. 00:00:32 The second thing is once you've done that, you would export the Snippets that you would like to contribute and you will add it to the Repository that you forked and cloned down to your developing environment and you would make commit messages on every change that you are intending to make. The second thing you would then do although there are few steps in each of these 00:01:03 things. The second thing is that you would then make a pull request.

1. Improving Existing Snippet 2. Move Existing Snippet To New Type 3. To Add A whole New Snippet Completely

In this tutorial I'm going to focus on the first few things you need to do and that is just to get you ready. All the things you need to do until the very point when you are now ready to do a pull request. There are three things that I suspect we can do. One is to improve an already existing snippet 00:01:36 And then contribute that to the community. The second thing is to move an existing snippet to a new type. This isn't something I hope will happen often, but it can happen that a snippet is in a specific type that is not the best suit for it. You might want to suggest to us changing that. The third one would be to add a whole new snippet completely. I'm just going to demonstrate all three of those 00:02:11 and then we'll see how that all plays out until the very point where we are ready to make a pull request.

Need To Do Homework And Study Git on Udemy - Use Links

First we need a repository and we need to understand Git. If you do not know Git this tutorial is not going to cover that you need to do your homework and study up on Git. 00:02:34 When you do an export of a package for example if I were to click on these three Grid, Panel and Block and click Share Snippets, you will see that it ends up showing you a bunch of links. One of them is https://www.udemy.com/git-quick-start/. This link, I've searched on Google and found it. I didn't watch it myself I hope it's not bad. If you got a better one please share it on the issue somewhere and we'll improve this link. Or even if you've got your own and you would like us to promote your 00:03:10 tutorials on Git, sure why not. We will support those who support our community very gladly. You need to get your head around some of the Git basics so that you can do a 00:03:26 fork of the JCB Snippets on GitHub and then make a pull request. This video https://www.youtube.com is the one I'm busy making. It will end up being that link, how to fork the JCB Snippets and all this done. Then after that I'll be making this video(making a pull request https://www.youtube.com. We'll get to that in a moment. 00:03:49

Need An Account On GitHub

You need an account on GitHub. I'm going to use my own account and simply go and fork the repository and use that as demonstration. So needless to say I've got an account I've gone through all those hoops and now I'm simply going to fork 'This repository'. To get to 'This repository' it's this URL https://github.com/vdm-io/Joomla-Component-Builder-Snippets. Another way to get 'This repository' 00:04:16 is you go to Get Snippets and then the moment it's finish loading there is a link that you can click which will take you to the GitHub repository and it's this link gitHub. We could click that and as you see we end up at the same place. You could either just follow this URL up here or use that link. But you want to get to Joomla-Component-Builder-Snippets. 00:04:47 Since everybody that wants to contribute will need to fork it. I suspect this number here(Fork 1) will change and of course this repository is like 6 days old. I haven't even finished the README. There will be a lot of changes to 'This repository' and it will improve.

Forked Repository

The first thing you do is click on the button Fork and Forked repository. This will then ask you to select where you want to fork it, if you belong to organizations whatever. By then I don't need to explain to you how it works. If for some reason you don't, then you select your personal or whatever organization 00:05:27 you want the fork to appear in and then it will copy this repository for you. It's busy doing that. I'm copying it into my personal account.

vdm.io/Joomla-Component-Builder-Snippets - The Upstream Or Master Branch - Main Branch

Good practice: Every time you want to make a change then 00:05:48 you need to follow a few steps in having 'This repository' in sync with the what we call upstream repository. This vdm.io/Joomla-Component-Builder-Snippets is what we call the upstream or the master branch or whatever you want to call it, this is the main branch. The one that is being used inside of JCB. Yours isn't directly being used. Whatever changes you make here would not necessarily affect us at all, 00:06:20 but you want to commit your changes to your branch and then make a pull request to the upstream branch where you would like to share this with the community. That's sort of a quick explanation. We'll do this slowly. I'm not going to do the pull request in this tutorial 00:06:42 but I'll take you all the way up to the wall and then we will get the ladder out and finish that in the next tutorial.

Clone Repository Down To Your Own Developing Enviroment

Once you've done this forking of the main repository, you need to clone this repository down to your own developing environment. That is what I'll do next. You would click on Clone and depending on how you've got git set up on your developing environment. 00:07:14 Again those tutorials you'll need to do before coming here. You would select either SSH or HTTPS. I would suggest using SSH as this is of course more secure. We'll just copy git@github.com:Llewellynvdm/Joomla-Component-Builder-Snippets.git and then I'm going to use my users home folder for now. I am in the command line. I'm running Linux so if you're using Windows 00:07:47 you'll need to watch tutorials on how to do Git in Windows. You might end up using a tool instead of command line, but if you did that you'll also be having had watched tutorials to help you sort of understand what I'm doing. First we going to clone it. I've cloned it and we now have a folder call Joomla-Component-Builder-Snippets. I'm going to change it into that folder 00:08:19 with cd and a folder name: Joomla-Component-Builder-Snippets and there we go I'm in the folder and if I do ls - la we'll see all the files that was on GitHub in that folder. We want to change these files, but we're not going to change them directly. We're going to use JCB to do the dirty work for us because we might have issues with the scapeing and all kinds of things that can go wrong. So just to have good convention whatever changes you want to make, even if you want to add files or new libraries whatever, you do it in JCB and you do the export package. 00:09:01 You should check that if you export a snippet that it has three values always set. And those three values we'll scrutinize it when you make a pull request but that those name conventions be standard. It's quite important as you can see this, we've got the library name Uikit, it's uppercase u and space lowercase v2, then Common with uppercase. 00:09:33 (Common) is the type of snippet, then it's the name 'Animation' and obviously it is a json file.

Convention Builds By JCB

This is the convention and at this stage JCB builds that for you. I'm going to show you where it gets this convention. Because to follow this convention is really going to be very important if you're making new snippets for the Uikit v2 Library, 00:09:58 you need to ensure that your version 2 naming in your system is the same as it is here.

??? If you are adding a new library that isn't already in our repository, then you need to make sure that you use the naming as others will understand it as most common. The most common naming convention. And obviously if you need help on that you can open an issue and ask one of the admin Do you know Maybe give you a suggestion of what 00:10:31 To call the library But The Long end the short end of it is Please stick to the naming conventions Don't change this Uikit To maybe . . . remove the space here or something like that Because it will end up Just mismatching things and we want to avoid that from happening Ok so first thing we've done we've forked a repository and we've now cloned it 00:10:56 to offline developing environment And now I'm going to go to get sorry to JCB And I'm gonna export those three snippets the one is a new snippet The second is a changed or improved snippet And in the third is when you actually move a snippet to a different type The one I'm gonna target here Is let me see I Think it's it's not showing here now Oh here it this 00:11:27 Foo table The foo table snippet Is at the moment in layout I think there is a better Type for this snippet and I know the snippet isn't At this stage maybe the best We could add some more foo tables snippets but I'll leave that to some with you to do The point is I'm gonna move this one To the tables because it is a table right So that'll be the one change I'm gonna make then I'm gonna add one snippet 00:11:57 To the Uikit version 3 Since those snippets are still coming I'll just add one as demonstration and then I'll make a little change To one of these Snippets just for demonstration okay great let me do that Okay first thing a foo table click on that one Change it from layout to tables I'm not gonna make any other changes I'm just changing the type And this brings us to those three values that must always be set And shouldn't change unless it's really seriously necessary the one is the name You wouldn't wanna change this name unless you are a hundred sure it should be changed 00:12:41 Because in effect it will create a new snippet Because the way the snippets work it builds the file name With name The library and the type those three components together makes up the file name so changing any of those will in effect create a new snippet And create a duplicate And that's really what I wanna would try to avoid that And I realised This is gonna what I'm doing here now is inevitably gonna cause that 00:13:14 And I think it will show you why it's not a good thing to do it But so I'm doing this more really for demonstration And so the ideal reality is that when we add a snippet we add it to the correct library and type And give it the correct name From the start and that we don't need to change those three again If we do Most of the time I would expect That your pull request will be rejected Because this will mess up many conventions and cause Many duplicates across the system 00:13:49 In other developers' environment where they would import this new snippet And yet end up having two of the same snippets Okay I've said enough about that I hope you understand that how important this part is So let's go ahead save and close The next one I'm gonna do Is basically add a new snippet now since I've done this recording a second time now I've already done that and this is a accordion snippet here So you'll see that I've basically 00:14:23 Set that it's a JavaScript snippet It's an accordion It's you Uikit Version 3 I look down these types I'm wonder if some one of the other guys won't be better at this identifying of the types So I might even Not be the guy to make the call on this I really am open to some With better perspective who maybe knows these libraries assorting 00:14:51 ideas better I think there's a place called What is it Collapse Yeah collapse Accordions could also fit other under this Collapse I suppose let me do that I know the first accordion we added for Uikit version 2 That is actually found on the JavaScript But then we didn't have these many types 00:15:17 So I'll just add it under this Collapse for now Again I realise that this might be a difficult thing And What could help is going back to the actual library itself This This is the The link for it And to try and see how they Organized it and that's the problem 00:15:40 Uikit Didn't Give more breakdown besides calling it components So it's only called a component it doesn't Specifically added into a type whereas Bootstrap is doing a little better at that So that's why I'm not sure exactly where to place it now Since Bootstrap Actually adds it under Collapse 00:16:07 I think we won't go wrong to do the same So save and close There we go we got now A very crazy risky change of a type And a new snippet now let me take another Snippet and just make a little improvement to it I think I would use this Uikit version 2 Form snippet I'm just gonna add some usage information to it 00:16:37 Okay there we go And I'm gonna save it save and close So now I've made a change Basically two This one This one and that one and So those are the only ones I'm actually going to share This one when I created it it added my details As the Contributor 00:17:00 Which if you created a snippet it will add your details you will notice when you create a new snippet It takes a while before it's finish saving and it's because it's actually phoning GitHub And trying to see if there isn't a snippet Already with that Relationship as I explained in a previous tutorial And that takes a while and I'm still wondering if that's the best idea If we should continue doing that I'm open for 00:17:28 Suggestions But at this stage we're just trying to confirm that That's snippet Wasn't already created And to avoid conflicts Now That means if it doesn't find it it adds your details which is set here in the option Global options And as I explained in that tutorial You can add your details and you would get some you know exposure out there in the community 00:17:55 With your details there With these that I've just changed The contributor will stay the same But your name will come in on the plain Layout And your GitHub name will display there as recognition for your support Okay so now and next thing share snippets Now the reason I made it that it actually compiles a zip File 00:18:23 is because it's easier to move around We could argue that we might want to just have it zip Or move Rather move the Files right into your local cloned folder And so I am thinking at this stage maybe We should add a switch here in the global options That could make you choose it to do this or the other depending on what is most convenient for you 00:18:52 So I'm gonna go take the snippet And then I'm gonna go and basically unzip it into That Repository that we've cloned So here we are in that folder I'm gonna first on zip it right here There there is those three files That we want to make part of the repository Now like I said I Actually clone the repository right into my user 00:19:23 Folder So let us go to that folder Just gonna cut this here Cut And then paste It right into that folder Now we are updating one file So it's asking it already contains this file Now so when you make an improvement on a file you'll obviously have to replace it 00:19:49 So we click replace Now that you've Added those two new files And you have Replaced one of them The third one You'll see that we now have this Foo table The tables version And we have it also 00:20:09 at the layout version now one of them needs to go We don't want duplicates So you have to remove this one but Don't remove it via the The Interface Use git To remove the file So that you can also add a message So that when you make your pull request and we see their files removed that we'll know why you did it 00:20:32 And obviously then it will become a discussion And this we'll demonstrate in the next tutorial Okay so let's get back to command line Here we are we can say git Status to see what happened and we see wow ok one of been modified and these two have been added The first thing we wanna do is remove the one that we don't want Now because we have chosen to leave spaces within our file names You'll need to In put the file name in quotations To ensure that it actually you know 00:21:10 Not misunderstand what you doing So we will go do a git rm for remove And then the file name So You could click tab after typing foo table about there and then lay out and it Well basically grab the name for you And then click enter So it is removed it if we now and do git status we'll see that it's in the deleted Area and you need to actually 00:21:45 Make a commit to Explain what you've done so it's git Commit m And removed table layout Since I Moved the Foo table snippet 00:22:00 to tables To the tables type So We're not at this stage exactly sure How we are going to What kind of conventions we gonna follow with these commit messages There are reasons to have a few conventions here I just haven't had time to sort of get my head around it so for now we'll just is keep it basic But I'm sure as to community develop these things will become more 00:22:27 Explained and so if you need help we'll most probably have some documentation up At some stage to get you to know how to Correctly do a commit message I mean just what you should say first and what you shouldn't say and those kind of things Okay so I've got a key that signs off every commit I make You may not have that don't worry about it it's not really compulsory at this stage It's just the way I can make sure that everybody knows 00:22:59 That it's me Okay Now The next thing here is we wanna Add these new file so if we do git Status we'll see that now that file has been Made part of the commit At the branch or the local files of this clone 00:23:18 And we wanna add those two other files The first one I'm gonna target Is adding the foo table which we just removed So git Status Oops Okay so now we've got that one added And we need to give it a commit message Now I understand When we are doing such 00:23:47 a dangerous thing as moving a snippet to another type I would expect us to actually make a commit message for every Step of what we're doing But if you're adding like whole new library and you got like 300 new snippets that you're contributing I wouldn't mind you adding all of that on the one commit message Just making sure that the it was exported via Joomla's component Builder So that we don't have You know the wrong kind of code within those snippet files And obviously we will at 00:24:25 Pull request we'll scrutinize those files and we will have to look through them to ensure That it won't make any one system unstable And so we basically got to police some of this to do ensure that nothing gets you know Merged into the master branch That will put every anyone at risk as much as as far as we are able to To prevent that we wanna do that Well we're working with snippets so it should be fine but just in case we wanna be careful So when you're making changes to one specific snippet And you're not really like doing 00:25:03 Many at a time I think be as detailed as you can in your commit messages Because the more we know of what you're doing I think the easier it will be too merge it into The branch and to basically approve your pull request So the next commit message I'm just gonna say Git commit Message update the foo table layout foo table dot json to foo table Table Foo table dot json 00:25:33 since it is more correct snippet type Okay so that would then Deal with that added file Now we want to add the accordion which is the the new snippet So it's just git add and we can select the file name There is a shortcut to this It's when you use the dot git dot add and that's usually when you have lots of files and you just wanna add them all so it's like I explained if you doing a whole bunch of snippets for a specific library I would suggest doing library per library instead of just mixing them all up 00:26:10 Because if we target a library and just add a bunch of stuff that's for it And then have a commit message just for that then we could explain that within the commit message That it's for the specific library and so forth Because usually with new libraries You know it's good for us too sort of take it one step at a time so now we've added that file now just got to add a commit message for it I'm just gonna say added the Accordion snippet For Uikit Version 3 as demonstration On how this should work 00:26:46 Okay and then just again Sign off that Commit Git status We'll see okay we've got one file left and we already three commits Ahead Of our Our Branch that we have Cloned 00:27:10 So just this last file which is the You know the update we made So We're gonna first add the file And then add a commit message To explain what we did Added the users paragraph to explain how to use the Uikit version 3 layout form Yeah I think just writing out the file name like that is Clear enough 00:27:38 And enter again just sign off on that Again if you don't have Keys to then It's good go Google this Start signing your request But at this stage it's not a requirement as I said Okay if we do git status now we'll see that we are four commits ahead Now this is here where We wanna do a few more things 00:28:06 To your Commit or sorry to your Your Forked And therefore cloned repository what we wanna do something that will keep Your Repository in sync with the upstream So I'm just gonna go and Google this quickly This is a very helpful document 00:28:31 We first need to do this configure a remote that points to an upstream repository So let's first look at that one So this gives you a little explanation Of you know what you should do So First you'd basically List the current Remote branches That you have 00:28:56 So I've done that and it shows that I've got this git or the origin And it's the fetched and the pushed Remote branches Now It's gonna say specify a new remote upstream repository that will be in sync with this fork So we'll use the original owner and the original repository Name Which In our case is the following The original owner is this 00:29:28 VDM Dot io and The repository is this one So to get that name You could come here And Yeah think you could get This name here There we go That part 00:29:48 copy So going back to our tutorial We will now type the Git and I suppose you'll have to get the https version Since you will not have permission to Work with the SSH version So let's get the http one Which basically means that you should click http here And then grab that version just copy it And 00:30:16 Control Shift v will paste it in Into command line or some Command lines even gives you this option to paste With a mouse Okay so now we got that there And we press enter So it's now Typo Let me try again 00:30:37 I didn't add remote add So it was looking for a file Okay there we go now if we did that version we'll see now It has this upstream there as well Okay so that was just to add the remote or the upstream Repository to the cloned Version that you have here 00:31:01 Now let's go see how to keep it in sync So here it says that you would open the terminal And you would do git fetch upstream And it will basically pull down This And make sure that there is a branch called upstream Master then you would checkout master And switch to the master branch and do merge upstream master Which if while you were busy doing the snippets improvements and things 00:31:30 And there's been commits to the master branch You wanna make sure That you Actually before pushing all this upstream Before making a pull request that you first merge The already changes from the master branch Into your branch and then make your commits on top of that This will help to try and avoid You not having specific commits in your branch I know it gets a little bit complicated 00:32:01 but If you get stuck We will most of the times be able to just help you Figure this out again But like I explained in the beginning To know how to work with git Is really your responsibility So that You when you are wanting to communicate or sorry to Share with the community snippets 00:32:23 You know how to first make a pull Request a sorry merge Your upstream with your master branch And ensure that you are up-to-date with that before making a push to your branch and Yes I hope you understand anyway if you don't please Google it and do some homework to get you Git Knowledge all freshened up and ready Now I know we didn't make any changes to the master branch during this tutorial So 00:32:56 I can demonstrate the process of Git Fetch Upstream And it will do that But since I know that we didn't actually make any changes In the end of the day We we will not be Really seeing any Great fireworks happening right now And I suppose some of you will experience it a little different 00:33:22 Especially if there's been changes to the upstream while you have been working So Git checkout master It's usually the branch that you're on but just to make sure You're already on the master branch Then Git Merge Oops I missed out the git there 00:33:44 Merge upstream master And it says like now it's already up to date If it wasn't it will actually Merge those two branches With the changes you've made Now That's what you should do before you do the following Git push 00:34:09 Which will now take these changes you've made And you wanna push them to origin origin master Now Everything you've done All the commits you made all the commit messages the files you removed All of that now gets pushed up To your cloned version On GitHub 00:34:36 So if we go to your version now on GitHub And we just refresh the page It'll say This branch is for commits ahead of VDM-io master Which means you are now ready To make a pull request A pull request is what we will deal with in the next tutorial So everything we've done so far and this tutorial is to get the snippets that you've changed the contributions You wanna make Into the branch that you forked 00:35:10 And to do it in a way that you're not completely out of sync With the master branch Which is living Basically on VDM dot IO Joomla component Builder snippets This is the master branch that you forked So you've got those commits in your forked branch And now you want to actually make A pull request To much these changes you've made into that master branch 00:35:36 So that it will eventually become available To the whole community of JCB Okay thank you for watching If you have any issues Please Google Do research Git is an amazing technology and The quicker you can Get your hands on it and Become 00:35:59 Comfortable with working with it the better Okay Next tutorial we'll deal with the pull request