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 [email protected]: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 the most common naming convention. If you need help on that, you can open an issue and ask one of the admin to maybe give you a suggestion of what to call the library. 00:10:31 The short end of it is please stick to the naming conventions. Don't change this Uikit to maybe to remove the space between Uikit and v2 or something like that. Because it will end up mismatching things and we want to avoid that from happening. First thing we've done we've forked a repository and we've now cloned it 00:10:56 to our offline developing environment.

Export Snippets - New Snippet, Changed Or Improved Snippet, Move A Snippet To A Different Type

Now I'm going to go to JCB and I'm going to export three snippets. The one is a new snippet, the second is a changed or improved snippet, then the third is when you move a snippet to a different type. The one I'm going to target is 00:11:27 FooTable. The FooTable snippet is at the moment in Layout. 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 FooTables snippets, but I'll leave that to some with you to do. The point is I'm going to move this one to the tables, because it is a table. So that'll be the one change I'm going to make then. I'm going to add one snippet 00:11:57 to the Uikit v3. 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. First thing a FooTable, click on that, change it from Layout to Tables. I'm not going to make any other changes I'm just changing the Type.

Snippets Builds The File Name - Name - Library - Type

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 want to change this name unless you are a hundred present 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 the 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 want to would try to avoid that. I realized this is going to what I'm doing here now is inevitably going to cause that. 00:13:14 And I think it will show you why it's not a good thing to do it. I'm doing this more for demonstration.

Important: When Adding A Snippet - Add It To The Correct Library and Type, Give The Correct Name

The 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. I hope you understand that how important this part is. Save and close.

Adding A New Snippet

The next one I'm going to do is add a new snippet. Since I've done this recording a second time, I've already done that and this is a Accordion snippet. You'll see that I've basically 00:14:23 set that Type it's a JavaScript snippet. The Name is an Accordion. The Library is Uikit v3. I look down these Types, I'm wondering if some one of the other guys won't be better at this identifying of the Types. 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 Collapse. Accordions could also fit under this Collapse. I know the first Accordion we added for Uikit v2 that is found on the JavaScript but then we didn't have these many Types. 00:15:17 I'll just add it under Collapse for now. Again I realize that this might be a difficult thing. What could help is going back to the actual library itself. This the link for it: https://getuikit.com/docs/accordion 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. That's why I'm not sure exactly where to place it now. Since Bootstrap adds it under Collapse, 00:16:07 I think we won't go wrong to do the same. Save and close. There we go, we got now a very crazy risky change of a Type and a new snippet.

Improving A Snippet

Let me take another Snippet and just make a little improvement to it. I think I would use this Uikit v 2 form snippet. I'm just going to add some usage information to it. 00:16:37 Okay there we go. I'm ging to save it, save and close. I've made a change to FooTable, Form and Accordion. Those are the only ones I'm going to share. Now Accordion, 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. It's because it's phoning GitHub and trying to see if there isn't a snippet already with that relationship as I explained in a previous tutorial. 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 if that snippet wasn't already created and to avoid conflicts. That means if it doesn't find it, it adds your details which is set here in the Global options. As I explained in that tutorial you can add your details and you would get some 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 Blame Layout and your GitHub name will display there as recognition for your support.

Share Snippets

Next thing share snippets. The reason I made it that it 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. 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 I'm going to go take the snippet /media/host/Dropbox/sandbox/joomla/tmp/snippets. and then I'm going to go and unzip it into that repository that we've cloned. Here we are in that folder(see video). I'm going to first unzip it. There are those three files(see video) that we want to make part of the repository. Like I said I clone the repository right into my user 00:19:23 folder. Let us go to that folder. I'm going to cut this here. Cut and then paste it right into that folder. We are updating one file. It's asking if it is already contains a file? When you make an improvement on a file, you'll 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 FooTable, the Tables version, and we have it also 00:20:09 at the Layout version. 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 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 our files removed that we'll know why you did it. 00:20:32 Obviously then it will become a discussion. This we'll demonstrate in the next tutorial.

Back To Command Line - git status To See What Happened

Let's get back to command line. We can say git status to see what happened. We see one of has been modified and these two have been added(see video). The first thing we want to do is remove the one that we don't want. Because we have chosen to leave spaces within our file names, you'll need to put in the file name in quotations to ensure that it 00:21:10 did not misunderstand what you doing. We will do a git rm(for remove), and then the file name 'FooTable - (Layout) FooTable.json'. You could click tab after typing FooTable about there and then Layout and it grab the name for you. Then click enter. It is removed it.

Commit Message

If we do git status, we'll see that it's in the deleted area and you need to 00:21:45 make a commit to explain what you've done. It's git commit -m "removed FooTable - (Layout) FooTable.json since I moved the FooTable snippet 00:22:00 to the Tables type." We're not at this stage exactly sure what kind of conventions we going to 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. For now we'll just is keep it basic. I'm sure as the community develops 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. 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.

Adding A New File - Do git status - commit - git add

The next thing here is we want to add these new files. We do git status, we'll see that file has been made part of the commit, or the branch or the local files of this clone. 00:23:18 We want to add those two other files. The first one I'm going to target is adding the FooTable - (Table) FooTable.json which we just removed. Do git status. We've got that one added. We need to give it a commit message. 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 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 the wrong kind of code within those snippet files. We will at 00:24:25 the pull request, we'll scrutinize those files and we will have to look through them to ensure that it won't make any system unstable. We basically got to police some of this to ensure that nothing gets merged into the master branch that will put every anyone at risk as much as far as we are able to prevent that. We're working with snippets, so it should be fine but just in case we want to be careful. 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 to merge it into the branch and to approve your pull request.

git commit message update

The next commit message I'm just going to say git commit Message update the FooTable - (Layout) FooTable.json to FooTable - (Table) FooTable.json 00:25:33 since it is more correct snippet type. That would then deal with that added file.

Add New Snippet - Accordion - git add

Now we want to add the accordion which is the the new snippet. It's just git add and we can select the file name 'Uikit v3 - Collapse) Accordion.json'. There is a shortcut to this, it's when you use the .git.add and that's usually when you have lots of files and you just want to add them all. 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 add a bunch of snippets 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 it's good for us to take it one step at a time. We've added that file. We just got to add a commit message for it. I'm just going to say 'Added the accordion snippet for Uikit v3 as demonstration on how this should work.' 00:26:46 Then just again sign off that commit. git status. We'll see we've got one file left and we already have three commits ahead of our branch that we have cloned. 00:27:10 So just this last file which is the update we made. We're going to first add the file git add 'Uikit v2 - (Layout) Form.json' and then add a commit message to explain what we did. git commit -m "Added usage paragraph to explain how to use the 'Uikit v2 - (Layout) Form.json'. 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, go Google this. Start signing your request. But at this stage it's not a requirement as I said. If we do git status we'll see that we are 4 commits ahead.

Configuring A Remote For A Fork

This is where we want to do a few more things 00:28:06 to your Forked and therefore cloned repository. We want to do something that will keep your repository in sync with the upstream. I'm just going to go and Google this quickly. This is a very helpful document. 00:28:31 We first need to do this configuring a remote that points to an upstream repository. Let's first look at that one. So this gives you a little explanation of what you should do. First: 'List the current configured remote repository for your fork' branches that you have. 00:28:56 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. It's going to say: 'Specify a new remote upstream repository that will be synced with the fork'. We'll use the original owner and the original repository name which in our case is the following. The original owner is 00:29:28 vdm.io and the repository is Joomla-Component-Builder. To get that name, you could come here(Green Clone Button) and you could get the name vdm.io/Joomla-Component-Builder. 00:29:48

??? Copy the name. Going back to our tutorial. We will 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. Let's get the HTTP one which means that you should click HTTP here and then grab that version, 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