joomla/Component-Builder
joomla/Component-Builder
39
23
Fork 11
Code Issues 80 Pull Requests Projects 4 Wiki Activity

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

Amigo 2019-08-09 15:51:34 +02:00
parent fbe2eb82f5
commit ad73dd3a48
1 changed files with 23 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,33 +1,50 @@
# 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
[00:00:00](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h00m00s)
(_Click on these time links to see Youtube video_)
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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h00m11s) showing you how to take shared snippets and share them. 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 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 ### 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h00m32s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h01m03s) things. The second thing is that you would then make a pull request. [00:00:18](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h00m18s)
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. 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h01m03s) 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 ### 1. Improving Existing Snippet 2. Move Existing Snippet To New Type 3. To Add A whole New Snippet Completely
[00:01:10](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h01m10s)
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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h01m36s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h02m11s) and then we'll see how that all plays out until the very point where we are ready to make a pull request. 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h01m36s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h02m11s) 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 ### 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h02m34s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h03m10s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h03m26s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h03m49s) [00:02:19](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h02m19s)
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. 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h03m10s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h03m26s) 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.
### Need An Account On GitHub ### Need An Account On GitHub
[00:03:49](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h03m49s)
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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h04m16s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h04m47s) 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. 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h04m16s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h04m47s) 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 ### 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h05m27s) 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. [00:05:06](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h05m06s)
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 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 ### 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h05m48s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h06m20s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h06m42s) 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. [00:05:43](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h05m43s)
### Clone Repository Down To Your Own Developing Enviroment 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 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h06m20s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h06m42s) 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 Environment
[00:06:50](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h06m50s)
????
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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h07m14s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h07m47s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h08m19s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h09m01s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h09m33s) (Common) is the type of snippet, then it's the name 'Animation' and obviously it is a json file. 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h07m14s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h07m47s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h08m19s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h09m01s) 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](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h09m33s) (Common) is the type of snippet, then it's the name 'Animation' and obviously it is a json file.