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

Jump to bottom Edit New page

Amigo edited this page Aug 29, 2019 · 27 revisions

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

00:00:00 (Click on these time links to see Youtube video)

Now that a general overview of how things work in the new Snippet Manager has been given, the next step is to illustrate how to take shared snippets and share them.

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

Two things should be done. One is to fork the JCB community Snippets on GitHub and to do that you need to have a GitHub account. The second thing is to export the Snippets that you would like to contribute and add it to the Repository that you forked and cloned down to your developing environment and make commit messages on every change that you are intending to make.00:01:03 The next thing is to make a pull request.

1. Improving Existing Snippet

2. Move Existing Snippet To New Type

3. To Add A whole New Snippet Completely

00:01:10 This tutorial's purpose is to take you, step by step to the point where you will be ready to do a pull request Three things can be done. One is to improve an already existing snippet and then contribute that to the community. 00:01:36 A second option is to move an existing snippet to a new type. Hopefully, that will not happen often, but a snippet may be in a specific type that is not best suited for it. The third one would be to add a whole new snippet completely. I am going to demonstrate all three of those. 00:02:11

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

First, we need a repository and need to understand Git. If you do not know Git this tutorial is not going to cover that, you need to study up on Git. 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/. I have found this link on Google but did not watch it. If you got a better one please share it on the issue and we will improve this link or if you have your own and you would like us to promote your tutorials on Git, sure why not. 00:03:10 You need to get your head around some of the Git basics so that you can do a fork of the JCB Snippets on GitHub and then make a pull request.00:03:26 This video 'https://www.youtube.com' is the one I am currently presenting. It will end up being that link, 'how to fork the JCB Snippets' and all this done, I will make this video ('making a pull request https://www.youtube.com.'

Need An Account On GitHub

You need an account on GitHub. To demonstrate, I am going to use my account and simply fork the repository and use that. I am going to fork 'This repository'.

Use this URL https://github.com/vdm-io/Joomla-Component-Builder-Snippets to get to 'This repository'.00:04:16 Another way to get to 'This repository' is to go to 'Get Snippets' and the moment it has finish loading there is a link which will take you to the GitHub repository and it is this link 'GitHub'. Use that link and you will end up at the same place. 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 have not even finished the README. There will be a lot of changes to 'This repository' and it will improve.

Forked Repository

The first thing is to use the 'Fork' button and Fork the repository. This will then ask to select where it should be forked, in case you belong to organizations or whatever, and if you do there is no need to explain how it works. If for some reason you do not, then select your personal or whatever organization you want the fork to appear in and then it will copy this repository. It is copied into my 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 you need to follow a few steps in having 'This repository' in sync with what we call; 'Upstream Repository'. This 'vdm.io/Joomla-Component-Builder-Snippets' is what is called the 'Upstream' or the 'Master' branch. The one that is being used in JCB is the main branch. Yours is not directly being used. Whatever changes you make here would not necessarily affect us at all, 00:06:20 but if 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. I am not going to do the pull request in this tutorial but I will take you to the wall and then get the ladder out and finish that in the next tutorial.

Clone Repository Down To Your Developing Environment

Once this forking of the main repository has been done, you need to clone this repository down to your developing environment. Click on 'Clone' and select either SSH or HTTPS depending on how you have got Git set up in your developing environment. 00:07:14 I would suggest using SSH as this is, of course, it is more secure. Copy '[email protected]:Llewellynvdm/Joomla-Component-Builder-Snippets.git' and then I am going to use my users home folder for now. I am in the command line and running Linux but if you are using Windows, you have to watch tutorials on how to do Git in Windows. 00:07:47 You might end up using a tool instead of the command line. First, it is going to be cloned. Now there is a folder called Joomla-Component-Builder-Snippets. 00:08:19 I am going to change it into that folder with 'cd' and a folder name: 'Joomla-Component-Builder-Snippets' and I am in the folder and if I do ls-la all the files that were on GitHub can be seen in that folder. We want to change these files, but not directly but use JCB to do the dirty work because we might have issues with the 'escaping' 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, do the export package in JCB. 00:09:01 If you export a snippet, see that it has three values always set. We will scrutinize those three values when a pull request is made but that those name conventions must be standard. It is quite important, we have the library name Uikit, it is uppercase u and space lowercase v2, then (Common) with uppercase. 'Common' is the type of snippet, then it is the name Animation slide-top reverse and obviously, it is a json file.

Convention Builds By JCB

This is the convention and at this stage, JCB builds that. I am going to show where it gets this convention. To follow this convention is going to be very important if new snippets for the Uikit v2 Library are made, 00:09:58 make sure that your version 2 naming in your system is the same as it is here. If you are adding a new library that is not 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 with 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. Do not change this Uikit to maybe remove the space between Uikit and v2 or something like that because it will end up mismatching things. The first thing we have done was to fork a repository and have now cloned it to our offline developing environment.

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

Now I am going to go to JCB and will export three snippets. The one is a new snippet, the second is a changed or improved snippet, then the third is a snippet that has been moved to a different type. The FooTable will be targeted. 00:11:27 The FooTable snippet is at the moment in Layout. There is a better type for this snippet. We could add some more FooTables snippets, but leave that to some to you to do. I am going to move this one to the tables because it is a table. I am going to add one snippet to the Uikit v3.00:11:57 Since those snippets are still coming. I will just add one as a demonstration and then make a little change to one of these snippets just for demonstration. The first thing is FooTable, click on that, change it from Layout to Tables. No other changes will be made but to change the Type.

Snippets Builds The File Name - Name - Library - Type

This brings us to those three values that must always be set and should not change unless it is absolutely necessary. The one is the Name, do change it unless you are a hundred present sure it should be changed because in effect it will create a new snippet. The snippets build the File Name with the Name, the Library, and the Type. Those three components together make up the File Name, so changing any of those in effect will create a new snippet, and create a duplicate, that should be avoided. What I am doing here as an illustration, inevitably is going to cause that.

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

When a snippet is added, it should be added to the correct Library and Type and from the start given the correct Name so that it is not necessary to change those three again. Most of the time our pull request will be rejected because this will mess up many conventions and cause many duplicates across the system in other developers' environments when they import this new snippet. Save and close.

Adding A New Snippet

Next, I am going to add a new snippet. Since I have done this recording the second time, this 'Accordion' snippet is already in place. The Type is set so that it should be a JavaScript snippet. The Name is an 'Accordion'. The Library is Uikit v3. 00:14:51 I think there is a place called 'Collapse'. 'Accordion' could also fit under 'Collapse'. The first 'Accordion' we have added for Uikit v2 that was founded on the JavaScript but then we did not have these many Types. 00:15:17 I'll just add it under 'Collapse' for now. I realize that this might be a difficult thing. What could help is to go back to the actual library. This is the link for it: https://getuikit.com/docs/accordion and to try and see how they organized it. 00:15:40The problem is, Uikit did not give more breakdown besides calling it Components. So it is only called a Component, it does not specifically add it into a Type. Whereas Bootstrap is doing a little better at that. Since Bootstrap adds it under 'Collapse', 00:16:07 I think we will not go wrong to do the same. Save and close. Now we got 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 am going to use this Uikit v 2 form snippet and add some usage information to it and save it, save and close. A change has been made to FooTable, Form, and Accordion. Those are the only ones I am going to share. Now 'Accordion', when I created it, it added my details as the contributor. 00:17:00 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 is completely saved because it is phoning GitHub and trying to see if there is not a snippet already with that relationship as I explained in a previous tutorial. That takes a while and I am still wondering if that is the best idea if we should continue doing that. 00:17:28 I am open for suggestions but at this stage, we are just trying to confirm if that snippet was not already created and to avoid conflicts. That means if it does not 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 with your details there. With these that I have 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. I made it compile a zip file so that it is 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. Maybe we should add a switch here in the Global Options that could give the option to select the one or the other depending on what is most convenient for you. 00:18:52 I am going take the snippet '/media/host/Dropbox/sandbox/joomla/tmp/snippets' and unzip it into that repository that has been cloned. (see video). First, unzip it. There are those three files(see video) that we want to make part of the repository. The repository is cloned right into my user folder. 00:19:23 Go to that folder and cut this (Please follow on video). Cut and then paste it into that folder. One file gets updated and asks if it already contains a file? When a file is improved, it should be replaced. 00:19:49 Therefore click 'Replace'. Now that you have added those two new files and have replaced one of them, the third one will now have this FooTable, the Tables version, and it is also at the Layout version. 00:20:09 One of them needs to go there should be no duplicates. Remove this one but do not remove it via the interface. Use Git to remove the file so that you can also add a message so that when you make a pull request and see our files removed that we will know why you did it. Then it will become a discussion. This will be demonstrated in the next tutorial.

Back To Command Line - git status To See What Happened

Back to the command line. Say git status to see what happened. One has been modified and these two have been added(see video). The first thing is to remove the one that is not needed. Because we have chosen to leave spaces within our file names, then put the file name in quotations to ensure that it does not misinterpret what you doing.00:21:10 Then do a git 'rm'(remove), then the file name 'FooTable - (Layout) FooTable.json'. You could click tab after typing FooTable and then Layout and it grabs the name. Then click enter. Now it is removed.

Commit Message

If a git status is done, we will see that it is in the deleted area and you need to make a commit to explain what you have done. It is git commit -m "removed FooTable - (Layout) FooTable.json since I moved the FooTable snippet to the Tables type.00:22:00 We are not at this stage exactly sure what kind of conventions to follow with these commit messages. There are reasons to have a few conventions here, I just have not had time to sort of get my head around it. For now, we will just keep it basic. I am sure as the community develops these things will become more 00:22:27 explained and so if you need help we will most probably have some documentation up at some stage to get you to know how to correctly do a commit message. I have a key that signs off every commit I make. You may not have that so do not worry about it, it is not compulsory at this stage. It is only to identify yourself.

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

The next thing here is to add these new files. Do git status, 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 to target is adding the FooTable - (Table) FooTable.json which we just removed. Do a git status. With that one added, give it a commit message. 00:23:47 Since it is so dangerous to move a snippet to another type, do make a commit message for every step. But if you are adding like the whole new library and are contributing like 300 new snippets, it will be okay if you add all of that on the one commit message. Just ensure that it was exported via Joomla's Component Builder so that there would not be any wrong kind of code within those snippet files. At the pull request, we will scrutinize those files and have to look through them to ensure that it will not make any system unstable. 00:24:25 It have to be policed to ensure that nothing gets merged into the master branch that will put everyone at risk. When you are making changes to one specific snippet and does not like doing many at a time, be as detailed as you can in your commit messages.00:25:03 The more we are aware of what you are doing, 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 -m Updated the FooTable - (Layout) FooTable.json' to 'FooTable - (Tables) FooTable.json' 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 new snippet. It is just git add and we can select the file name 'Uikit v3 - Collapse) Accordion.json'. There is a shortcut to this, it is when you use the .git.add and that is usually when you have lots of files and just want to add them all, it is like I explained if you are 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 is for the specific library and so forth because usually with new libraries it is good for us to take it one step at a time. That file has been added. We just have to add a commit message for it. I am going to say 'Added the accordion snippet for Uikit v3 as a demonstration on how this should work.' 00:26:46 Then just again sign off that commit. git status. We have one file left and already have three commits ahead of the branch that we have cloned. 00:27:10 So just this last file which is the update we have 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 and enter. 00:27:38 Sign off again on that. If you do not have keys, go Google this. Start signing your request. But at this stage, it is not a requirement. If a git status is done we will see that we are 4 commits ahead.

Configuring A Remote For A Fork

This is where we want to do a few more things 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'.($ git remote) 00:28:56 With that done, it shows 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 will have to get the HTTPS version since you will not have permission to work with the SSH version. Let's get the HTTPS one which means that you should click HTTPS here and then grab that version, copy it and 00:30:16 control shift v will paste it in, into the command line or some command lines even gives you this option to paste with a mouse. Okay, so now we got that there and press enter. 00:30:37 I didn't add remote add so it was looking for a file. If we did that version we'll see it has this upstream there as well. That was just to add the remote or the upstream repository to the cloned version.

Syncing A Fork (See Video)

How to keep it in sync. It says that you would open the terminal and you would do $ git fetch upstream. It will pull down this and make sure that there is a branch called upstream master. Then you would check out the master and switch to the master branch and do $ git merge upstream/master which if you were busy doing the snippets, improvements and things 00:31:30 and there has been commits to the master branch, you need to make sure that before pushing all this upstream, and before making a pull request, that you have first merged the changes from the master branch into your branch and then make your commits on top of that. This will avoid having non-specific commits in your branch. 00:32:01 If you get stuck, we will most of the times be able to help you figure this out. But like I explained, in the beginning, when you want to share snippets with the community you should know how to work with Git 00:32:23 and know how to merge your upstream with your master branch and ensure that you are up-to-date with that before making a push to your branch.

Git fetch upstream - Git checkout master - Git merge upstream master

No changes to the master branch had been done during this tutorial. I will demonstrate the process of git fetch upstream. Since we did not make any changes, there would not be any great fireworks. Perhaps some of you will experience it a little different 00:33:22 especially if there have been changes to the upstream while you were busy working. git checkout master is usually the branch that you are on but just to make sure you are already on the master branch, type git merge upstream master. It indicates like now that it is already up to date. If it was not, it will merge those two branches with the changes you have made.

git push - Everything You've Done Gets Pushed To Your Cloned Version On GitHub

Then git push will now take these changes you have made and push them to origin master. Everything you have done, all the commits that were made, all the commit messages, the files you removed, all get pushed up to your cloned version on GitHub. 00:34:36 If we go to your version on GitHub and refresh the page, it will say: 'This branch is 4 commits ahead of vdm-io:master'. Which means you are now ready to make a pull request. A pull request will be dealt with in the next tutorial. So everything that has been done so far in this tutorial is to get the snippets that have been changed, the contributions you want to make to the branch that you have forked, and to do it in a way that you are not completely out of sync with the master branch which is living on vdm.io/Joomla-Component-Builder-Snippets. 00:35:19 This is the master branch that you forked. So you have got those commits in your forked branch and now want to make a pull request to merge these changes you have made into that master branch so that it will eventually become available to the whole community of JCB. If you have any issues please Google, do research.