Contribute to the official kits
Typically, as prismic.io users realize how much power prismic.io brings to their content management, they also come to realize that the kits are designed to be overriden and extended (for instance, to customize the output of some asHtml functions), effectively giving them even more power.
Sometimes, some of our users find ways to make our kits even more able to empower developers, and we're always glad to get feedback to make the kits better. This is why the kits are all open-source and available on GitHub, because we trust that the community is the best mean to help building the kits that people actually need. However, some of our motivated users are not necessarily as familiar with Git or GitHub as we are, and this guide is here to help them contribute, regardless of their level.
If you need information about the difference between a "development kit", a "starter project" and an "example", or if you wish to build a new kit for a technology that we don't officially support yet, you should read our "How to build a library for your technology" documentation article.
For experienced Git/GitHub users: we use the "fork and pull" collaborative model (if you're not familiar with it, don't panic, then the rest of this guide is for you!)
A few simple guidelines:
- Make sure to submit atomic commits, with a clean history.
- Please do test and document your code. If you find existing code that is not optimally tested or documented and wish to make it better, we really appreciate it; but you should document it on its own branch and its own pull request (so we can merge it faster).
- If you have in mind to build a new feature, you might be planning to code it in the wrong type of kit (development kit instead of starter kit, for instance), so you'll probably be better off mentioning it to us first to make sure. Create an issue (GitHub's internal ticket tracking - see the GitHub introduction below), we'll discuss it with you promptly.
- If you see something that can be optimized, but don't have the time / don't feel able to fix it, as much as we love pull-requests, this is invaluable information, so it would be nice for you to open a GitHub issue on the relevant repository.
Git and GitHub in a nutshell
Git is a source code management (SCM) software, allowing to easily version source code and work on it collaboratively, also making you able to effectively track changes. If you've worked with softwares like SVN, CVS, SourceSafe, Bazaar, Mercurial, BitKeeper, Perforce, etc., this is the same family of software, although Git's approach may be very different to the one you're used to.
There are graphical UIs for Git depending on your OS, but they rarely embody Git's full power, that only the command line can leverage; in this guide, although we cover only basic Git, we'll be using the command line. To understand this guide fully, you need to understand at least what a branch is (a "fork" in the code history, on which you can iterate without impacting the master branch, which is the main one that everyone uses), what a merge is (when you make two branches into one; for instance, you can merge your temporary branch into the master branch once it's ready, so that the master branch get your changes), and what a commit is (the smallest step in the versioning history; basically you should commit each time you made changes that are meaningful to keep together, and that are stable). Here is a great further description of Git's basics.
GitHub is a service that provides a Git repository "server" that people can synchronize with; it also provides a nice interface on top of many of the basic Git's features, as well as collaboration tools that are not part of Git (social comments, code review, issue tracking, ...)
Two types of pages will interest you as a starting point:
- Organization pages: our prismic.io organization page https://github.com/prismicio lists all of prismic.io's open-source projects. Your own "repositories" page looks a lot like it, except it's your projects that are listed: https://github.com/<your_username>?tab=repositories . If you click on one of the projects' names, you'll end up on the project's repository page.
Install basic tools (once and for all)
If you don't have one yet, create a GitHub account. If you don't have it yet, install Git on your computer and set it up. Also, if you don't have one, think about creating a repository on your filesystem where you will be storing your projects.
Depending on the kit you'll be working with, you might need to install some other software:
- for the Ruby development kit, you have to install at least Ruby, RubyGem and bundler.
Fork and create your environment (once per kit)
Here, we'll do two things:
- "fork" the repository, so that GitHub creates your own exact copy of it on your account, on which you can do anything you want;
- and then "clone" this newly-created repository into your computer, so that you can manipulate it locally.
Forking the repository is done by clicking on "Fork", on the top-right of the GitHub repository's page belonging to the prismicio organization account (see image below). If you're part of organizations, you then might have to choose which accounts you wish to fork it into.
To clone it, you need to copy the URL from the "HTTPS clone URL" input, on your own repository's page (see image below), and call it in your terminal with the git clone command. It should look like this:
So now we have three copies of the repository:
- one on prismicio's official GitHub organization account;
- one on your own personal GitHub account (GitHub will always remember it was created from the official one, and you can't edit this "link");
- one on your computer's disk, which is already linked with your GitHub account as a remote.
A remote in your local repository is a distant Git repository that you can locally push to (send commits to) and pull from (get the newest commits recently made by other people). Right now, your local repository has only one remote, the Git repository on your personal GitHub account, and it gave it the name origin. To see your current remotes and their URLs, you can run:
git remote -v
It's all good as a working workflow to push changes, you don't need much more (we'll details these steps in the next paragraphs):
- you'll make your changes and commits on your local repository;
- you'll push them to your own GitHub repository so people can access them (easy to do: one is linked to the other as a remote);
- you'll notify people that you've posted commits online and that they should pull them into the official repository (easy to do: GitHub remembers the "link" between your repository and the official one);
- we'll pull them from your repository, into the official one.
The only use case that is not covered by all these linkings is what you're supposed to do before you start working on each new bugfix or feature: you will obviously need to update your local repository with the changes made by other people since last time. Therefore, we'll also add the official repository as a local remote too.
Let's create that remote we'll be able to pull from, and let's call it "prismicio" (to reflect the name of the official GitHub account it's refering to):
Of course, this URL above was copied from the "HTTPS clone URL" input, on the official repository's page this time.
Make changes and commits in your local repository
If you remember, the master branch is the name of the main, stable branch, that everyone uses. Your local repository and your personal repository both have a master branch, but we're going to ask you to please never commit on it. That way, when you submit your changes as a branch, we can help you make that branch better, before merging it into the master branch.
You can always see a list of your local branches by running:
First, please go to your master branch if you're not already there (we say: check your master branch out), and before anything, you should probably pull it from the official repository, in order to get the commits that people might have made on the official master branch since last time you updated it:
git checkout master
git pull prismicio master
Then, you can create your branch and check it out in one step (you may call your branch however you want, but short names are preferable, because you might have to type it often later):
git checkout -b branch_name
You can create any amount of branches you want, and check them out at will, which will enable you to work on several bugfixes or features at once without them collapsing into each other, even if you work on the same files. Just remember to check the master branch out and pull it from the official GitHub account before creating a new branch, to make sure you're iterating on the most recent version of the master.
Making / committing changes
When you change any file in your local repository, Git notices it immediately. To see the detailed changes, you can ask Git:
To ask Git about the current status of the files in the repository (which were changed? renamed? deleted?), you can run at any time:
It will list the changes you've made, but it will also tell you that they were "not staged for commit". Indeed, once you're happy with a minimal set of stable changes, and think they could make a relevant stable commit, you'll get to say which files you'll want in that commit one by one:
git add src/file_that_was_changed.js
git add src/entire_repository/
You can also simply say that you need all the files that were modified within the repository to be in the next commit:
git add .
If some files were deleted or renamed, you might be requested to run this, for confirmation that you wish the deletion/renamings to be committed as well:
git add . --all
Before you commit all those changes, you should probably check one last time what you're about to commit, and make sure no unwanted file is staged to be in the commit you're about to make:
Once you're good, you can commit:
git commit -m "Your commit message: please make it relevant and meaningful"
At any time, you can review all the commits that were made on your current branch, by yourself or by other people, running:
Once you made your commit, you can go on with other changes, and when you're happy with them, git-add the files and make another commit, and so on, ...
Pushing to your personal GitHub repository
Do you remember the name of the branch you created for the feature or bugfix you're working on? If you're not sure, remember you can see the branches you have locally by running:
Remember that your local repository knows your personal GitHub repository as a remote called "origin"; to push your branch onto it, you can simply run:
git push origin branch_name
Request that we pull your changes into the official repository
Once you pushed your changes on your GitHub account, they're visible to the world, but you need to explicitely request us to pull your branch so that we get notified to look at it, and so that we eventually merge it; this is called "submitting a pull request". GitHub requires you to do it explicitely because many people make changes for themselves without them to be necessarily relevant for other people. By submitting us a pull request, you're offering your changes to be part of the official kit, used by everyone; this is the power of open-source!
- If you pushed the branch recently (the past few minutes), GitHub will show you an information message to offer you a quick way to submit it as a pull request; this is perfect, you can go ahead and click on it.
- If you're not getting that message, you will have to go get on the proper branch (the right arrow below), and click the green "Compare & review" button (the left arrow below).
You should write a meaningful comment to explain what your changes are for (anything that will make us understand better your intent and approach), and then click "Send pull request". You're done!
Pull requests usually don't get merged on the first attempt, and the group often has constructive criticism to help you make your branch better. To iterate on your pull request before it's merged, you can go back on your local branch, make your changes and commits, and push the branch to your personal GitHub; the pull request will then be automatically updated with the new changes. Think about notifying us though (by commenting in the pull request on GitHub): GitHub doesn't especially tell us when you update a pull request.
Hooray, my branch was merged! What now?
You're done, and you can be proud of yourself! But there's a thing or two you might want to do to get back to a totally clean state. Indeed, you still have a named branch locally, and also one in your personal GitHub repository, and you don't really need this branch anymore, since it's now part of the master branch anyway.
To delete the now unnecessary branch from your GitHub repository: when you receive the e-mail notifying you that your pull request was merged, click on "view it on GitHub". Near the bottom of the page (just above the comment form), you'll find a "Delete branch" button.
To delete the now unnecessary branch from your local repository, you first need to update your master branch, and then you can delete it safely:
git checkout master
git pull prismicio master
git branch -d branch_name
Fortunately for us, this last command is pretty coward: it won't do anything unless it's sure all of your commits on that branch are safely merged on the master branch. Therefore, if the last command worked with no warning, then you're now done for good!