062 Add your own JCB packages to the JCB Communty Directory

Jump to bottom Edit New page

Amigo edited this page Sep 27, 2019 · 10 revisions

ADD YOUR OWN JCB PACKAGES TO THE JCB COMMUNITY DIRECTORY

Import JCB Packages - New Tab Called Community Packages

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

I want to demonstrate the way to add JCB packages to the Community Directory. The moment if you go to Import JCB Packages, there is now a new tab called Community Packages. We would like to encourage all of you to start sharing packages. The main focus or purpose for it would become, to be a quick start for developing Components. 00:00:28 It could serve as a back up for yourself to easily pull on old packages that you have developed. To maybe have a specific feature, for example linking your Joomla users into your component. I know have some components that do that. I often want to reuse that. 00:00:52 You can now with this new idea be able to import that component over and over without merging it with the old version, but creating a new component, including fields and everything else. That is a way you will be able to quickly start a new project. You do not need to do all that over again.

The Clone Feature

It is sort of similar to the Clone feature that now has become available. The JCB components now have a Clone feature. You could select a component and you can clone it. In cloning, it creates an exact copy of the component, but not linked to the components. Even did Admin Views. You will see that it creates a new Admin View. 00:01:44 The same goes for the fields. You can create a whole new set of fields, specifically for this component. You will see it have the same Suffix (EO). That is the Clone feature.

The Import Feature - Merge Yes Or No

The import feature has the same functionality. If for instance, we would import the Demo component, then once we have the component from GitHub, we will see that it has this Merge option 'Yes' or 'No'. Remember we already have the Demo component, and it is exactly the same component, but I do not want it to update this one, 00:02:33 I want it to bring it in as a new component, and then I will tick this to 'No'. It does give you a little explanation and tells you the validation rules, Field types, snippets, languages, and language strings. These things will still be merged, that simply is unavoidable. If you want to see what happens under the hood, click on 'Continue'. 00:03:03 It will give you a whole lot of information about the import and also whatever files it moved. It created a new component. It did not update the old one. That is a very nice option because you can quickly start with this component without affecting this one. Now you will see that even the Admin View is dislocated, it is not the same Admin View. The same again with the fields. If we look at the fields, you will see it also has the (Ra) Suffix to it. 00:03:36 This name does not appear anywhere in the compiled version of the components, it is all system names. This (Ra) will just be for you to know that this field belongs to this component and so on. That is what the new JCB Package Import option has been improved to manage.

Community Option - Sharing

Now with the community option, you can do what we call 'Share'. Like I have been doing, sharing much information with all of you, components, tools. The idea that all of you would have this attitude of giving back to the community and the other option is that if you want to distribute a package, at the same time, maybe get some marketing, this is also going to be doing that. 00:04:33 Let me illustrate to you the process of getting a package into the Community Packages. We are going to use GitHub. This repository, JCB community Packages, this is the URL vdm-io/JCB-Community-Packages. 00:04:57 You will need to fork this package. I am not going to teach you how to use GitHub, neither how to use Git.

Demonstration - When Adding A Package Must Start Forking The Repository

I am going to illustrate what you need to do, demonstrating it to you. You need to go and study GitHub and Git specifically to be able to manage this. What will happen is anyone who wants to add a package, must start by forking the repository.

Once it has been forked, they need to clone it down to their the developing environment where they have JCB or to where they can move a JCB Package because at the end of the day they need to add their package which they want to contribute to their forked version of this JCB Community Packages.00:05:53 Once they have done all that and pushed up the changes to their repository, they will make a pull request to add the change into the Community Version of this repository. I hope that all makes sense to you. You will get the URL (Clone or Download) 00:06:14 on your own repository, copy that and then go to your developing environment. Hopefully, it will be Linux because you need to run a 'hash.sh' script. It needs to be a 'hash' environment. You could run it in a VM where ever you want, just get it going.

Open A Terminal - Cloning The Repository

I am going to open a terminal. In the terminal, I am simply going to clone this repository. Once it is finished cloning, we are going to change it to that directory. If we list out the items, you will see that it is exactly the same as what we have here on GitHub. It is literally the same information. 00:07:13 It is a folder on your computer. We will then need to go to JCB, extract the package you want to share, and simply place it into this folder. Run this hash.sh script. We are in our JCB program 00:07:39 and I want to share this question and answers component. I want to ask that you would not share things that do not work. If you are still busy developing the thing then it is not time to share it yet. When it is ready and you know that it works, that means if you have compiled it and tested it, and you know it stable, then you may share it. It does not need to be a big component, it could have just one view as long it is something other than what already exists. No more new demo components, it needs to be something else. 00:08:15 Please always check that if you want to contribute something, let it be something that is not already there. If there is already one, and you want to improve it, sure then you can do that. You can pull it in, make it better and make a pull request to improve it. Know that we will have to be able to test it if you are using a key, 00:08:42 you can not contribute it without a key back. If someone places a package in the Community and it has a key, then it lockout everybody else.

Helps Get Projects Going Quite Quickly

I am not exactly sure how all this is going to work out. I am very open to all of you to just give me feedback, input how you think this should be done. The idea is not to infringe on each other's projects but to help each other get projects going quite quickly. That is really the agenda. The idea is if you want to build a project, let's get something that can serve as a base from which to start. This question and answers program is a very nice base. It has a few views and fields. It has a very simple straight forward implementation of Q&A for your front-end of your website. I thought this is a nice thing to use as a demonstration.

First Visit Video - Watch The Video - Give A Free Key

Let us go to the component. Those of you who want to maybe give away the component, but you want to have people first visit a video that you have made, the way you could do this is, at this 'Buy Link', you will make that link to 00:10:23 direct to your video. When they click on the 'Buy Link', they will go to the video where you are going to give them the key for free. They can watch the video, get the key come back and open the package. We are not currently implementing 'Package Link'. The 'Package Link' should be where the package is, which most of the time will be the repository. 00:10:45 That is why we are not fully implementing this because we do not need it. We left it for future purposes. At the moment we do not need it the way we have set up things. You can use the 'repo' URL. It is only the Buy link that is really important. If it is a free package or not, but you are giving the key away. The other idea is not to add a key at all. If you do not add a key, then it will be a free package. 00:11:21 By leaving the key out you make it a free package. Whereas if you leave the key in, people will have to get the key from you. If you have it contributed to the community, you will need to share the key with the admin of the repository. 00:11:43 They can validate the component and check that it is safe for distribution. Some things will be put in place, maybe a forum procedure on how to do this inside of JCB, or maybe just in the read more of the repository. There will be a heads up when that happens. The explanation is simple, if you want to have people have the key from you, wherever they need to get it, whether it is free or paid, it needs to be this link. 00:12:15 The Export key is what we used to build the key. You can put in anything here. Once you have all that in place, you will Export the JCB Package.

Once Component Exported - The Package Is Available - In Temporal Directory

Once you have the component exported, the package is available in a specific directory called "Temporal directory" in your developing environment. The package that you want to add to the repository, this 'JCB_QuestionsAnswers.zip' is the key that you now need to give to everybody that wants to use the package. The key can nowhere be found but on this page where you compiled it. 00:13:02 Store the key in a safe place, or use it in your video and give it to the people at the right time, however you like.

Next Step - Move Package Into Repository Which We Cloned Down

The next step would be to move the package into the repository which we have cloned down to your local developing environment. I have the folder open where the package is. There is the following path which we looked at previously. We are going to drag and drop the file into the other folder where that cloned repository is at the moment, in my home folder. The package has been added and we are done. 00:13:56 We can close this one and return to the terminal.

In Terminal - git status - Run hash.sh Program Which Is A Bash Script

Once in a terminal, you can say 'git status', it will tell you that one file has not been tracked. Before you add the file, you will first need to run the 'hash.sh' program which is a 'Bash' little script. You will need Bash to run two other programs. It's this 'jq' and 'sha1sum'. These two programs are required and the script will shout at you if it does not exist. 00:14:48 You can Google JQ Bash Install and it will give you information to add these two programs to your developing environment and run that script.

What Does The Bash Script Do?

What that script will do is very simple. It will go through the files in the repository that are zip files, it will create a sum, and will place the sum in a file with the same name, except the sh added to the file name. It adds it there. It will get a shopFileName and then unzip the file to get the 00:15:28 info.vdm file from the zip package. Then change that to the shopFileName which should be the same as your package name, with info as the prerogative which is what we need to show the people what your package name is, and who owns it and these things. That is where that info comes from. It takes the information and it adds it to an array which then later gets written to the checksum.json. It is all it does. 00:15:55 Some little Bash gets the information from the file for you without your having any issues, it follows convention. I am going to go run the file. You add the dot, make sure you are in the repository, 00:16:21 ./hash.sh and enter. It should do that, as simple as that. It should not take long and if it did, then something is wrong.

Again - git status - checksum.json - git diff

If you again do the 'git status', you will see that there are 3 files that are not been tracked, and the checksum.json file has been modified. Why? because there is a new line been added to checksum.json. If we type in 'git diff', you will see that your component, the one that you are adding, is being added. That line was changed because it has a comma. But this is the new line that has been added. Add your component to the checksum.json. 00:17:15 That is all that should change. You should not change any other files in the repository. Only the ones that you are contributing are the ones that you must change.

git Add The Files - Comment - git commit am"Added Questions And Answers Packages

The next thing is to git add those files. Do git status, the words are now green. The comment, there is a lot of convention out there, I'm not keyed up with all of that. We can do 00:17:53 'git commit am"Added questions and answers package'. That's simple enough and then press enter. The m is for the message in the a is for pushing it all into the branch. If you have a passphrase 00:18:21 which you should have, then you have your commit signed. If you do not know how to sign commits in Git then please Google that and get your keys in place. We would expect that all commits to this repo be signed. Especially since we need to be sure that it is you that is making the commit.

When All Is Done - git push To Your Repository On Github

Now when you have done all that you do 'git' and you will push it up to your repository on GitHub. At this point, you are still not affecting the community repository. It is just affecting the repository that you forked. This is a very secure way of dealing with this. If we now go back to GitHub 00:19:11 were we fetch the page, you will see that it will say this branch is one commit ahead of VDM. There is make a Pull Request. You will make a Pull Request and it will take you to the main repository and will explain to you which one is being pulled where and it will tell you that it is able to be merged. The information is being added for the info 00:19:40 for the sha. and for the package which does not show because it is too big. You will see the Binary file not shown. There are also changes to the 'checksum.json'.

Create A Pull Request

Now at this point, you will need to create a pull request. Click on Create Pull Request. The comment that you made in your repository when you contributed the package, would be added as the title. If you want to give a little explanation of things that the admin team needs to consider because we have to test this. We can't add packages to the community packets branch without being able to test it. If you have a key for the package, we will create a form 00:20:35 where you will be able to submit that. We will put that in the information because at the moment this area does not even have a pull request template. We will add a pull request template when you create a pull request, it will tell you where to send the key. At the moment if there is no pull request, keep the packages that are coming that are free at the moment. As soon as the templates are in place then you can use it and then make a pull request. At the moment I am the only one that 00:21:07 manage this. I hope that others would get involved. There are some other developers involved in the JCB Repository, but I would like to also encourage them to get involved and be able to help me test these packages, make sure that only valid and stable packages get added. 00:21:30 Click Create pull request. I do not want to pull this into the repository at the stage. I am going to do it later. This is the procedure that you need to follow to get a package into the community packages because once it has been merged into the master branch, it will also become available on this page automatically. It will automatically show up in the dropdown. That is as simple as it is. If you have any questions please open an issue at the correct place. If you want to talk about the packages for the community, open the issue here. 00:22:27 Please do not make open issues at JCBs repository regarding this issue, so that we will have a clear separation between these two concepts.