This repo generates the content served on https://janusgraph.org
To make changes, you should install the local setup and once you're ready to submit changes, please provide a pointer to a previewable version via your published fork on GitHub. See instructions below for both of these below.
While developing the site, it is very helpful to have fast turnaround between
making changes and seeing how they work via Jekyll—you don't want to wait for a
git push
+ GitHub build cycle before seeing any changes. Thus, we want to
preview changes that we make using a local setup.
-
Install Ruby and Bundler
-
Install the necessary Ruby Gems for this repo into
.bundle
:make install
-
Run Jekyll locally to serve the site:
make serve
-
Visit https://localhost:4000/ to see the site. Now, any changes you make to
index.md
or any dependent files will be instantly previewable in your browser with a refresh.
Before pushing the site to production, and a great way to demonstrate proposed changes during code review, you should push the changes to your personal GitHub fork as follows:
-
Fork the website repo to your account via GitHub
- note: the
master
branch of this repo is the one that is auto-published to https://janusgraph.org soon after a commit
- note: the
-
Clone your copy of the repo locally
$ git clone [email protected]:[USERNAME]/janusgraph.org.git $ cd janusgraph.org $ git remote add upstream [email protected]:JanusGraph/janusgraph.org.git
-
Create a new branch for your changes, based on the latest changes in the
master
branch of the upstream repo:$ git checkout master $ git pull upstream master --ff-only $ git checkout -b [MY-BRANCH-NAME]
Note: the
--ff-only
flag enforces a "fast-forward" only merge, which guarantees that yourmaster
branch is a clean copy of the upstreammaster
branch. If yourmaster
branch cannot be fast-forwarded to match the upstreammaster
, this command will fail. It is recommended to never submit yourmaster
branch as a base of a pull request and only keep it to sync with upstream.This process ensures that your pull requests are always minimal and simple to review. This approach is also recommended when contributing to other git repos as well.
Always create a new branch for each new pull request; never push from your own
master
branch to a new PR, keep a cleanmaster
branch so that it stays in sync with upstream.Note:
[MY-BRANCH-NAME]
here is a placeholder for a brand-new branch name that does not yet exist in your repo; the command above will create this new branch for you. -
Make the changes you need and commit them to this branch.
-
Push your feature branch to the
gh-pages
branch on your fork on GitHub, so that everyone will be able to see a preview of your change:$ git push -f origin [MY-BRANCH-NAME]:gh-pages
Note:
[MY-BRANCH-NAME]
is the placeholder for the same branch name as selected above; this branch must exist at the time of running the above command.To simplify this process, you can also run:
$ make preview-via-github
which actually runs the following command:
$ git push -f origin $(git rev-parse --abbrev-ref HEAD):gh-pages
which automatically discovers the current branch you're on and pushes that to GitHub, using the
gh-pages
branch. -
Visit the "Settings" page for your fork on GitHub and make the
gh-pages
auto-publishable- note: after you make this change, you will get an email that you could not publish this site because the CNAME of janusgraph.org is already taken by another site (i.e., the canonical repo). You will also see a warning about this on the GitHub UI. Both of these warnings are safe to ignore because we are trying to create a personal test copy, not update the live site.
-
Now you can visit your site at
https://[your-username].github.io/janusgraph.org/
to see your changes -
Now you can push your
[MY-BRANCH-NAME]
to your fork to open a pull request using it.Important: do not use either
gh-pages
ormaster
branch to submit pull requests; use a separate feature branch for every change and every pull request, and delete each of those branches after the pull request is either merged or abandoned. -
Any changes you continue to push to your
gh-pages
branch will keep updating live on GitHub after a few minutesNote: you will get warning emails from GitHub saying that your repo is attempting to publish to the URL
janusgraph.org
which is already taken. This is fine; you can ignore these emails — it is saying that you cannot publish directly to that hostname from your private repo, which is correct.
-
First, update your
master
branch and pick up the latest changes, run:$ git checkout master $ git pull upstream master --ff-only
Note: the
--ff-only
flag enforces a "fast-forward" only merge, which guarantees that yourmaster
branch is a clean copy of the upstreammaster
branch. If yourmaster
branch cannot be fast-forwarded to match the upstreammaster
, this command will fail. It is recommended to never submit yourmaster
branch as a base of a pull request and only keep it to sync with upstream.This process ensures that your pull requests are always minimal and simple to review. This approach is also recommended when contributing to other git repos as well.
-
Then, update your feature branch via
git rebase
to avoid including other users' changes into your branch, which makes CLA verification harder:$ git checkout [MY-FEATURE-BRANCH] $ git rebase master $ git push -f origin
This repo uses a combination of Apache 2.0 and
CC-BY-4.0; see LICENSE.txt
for details.