For collaboration purposes, it is best if you create a GitHub account and fork the repository to your own account. Once you do this, you will be able to push your changes to your GitHub repository for others to see and use, and you will be able to create pull requests (PRs) in the official EGI documentation repository based on branches in your fork.
If you are new to
git and GitHub you are advised to start by the two
following articles providing simple tutorials:
GitHub official documentation is available at docs.github.com.
Additional documentation about the main steps for working with GitHub is also available in this section.
In order to be able to send code update to the repository you need to:
In this process three git repositories are used:
The most convenient way to authenticate with GitHub is to use SSH keys over the SSH protocol.
You can add an SSH public key to your GitHub account in the
GitHub, at https://github.com/settings/keys.
Refer to Connecting to GitHub with SSH for an extensive documentation on using SSH keys with GitHub.
It’s worth to mention that your ssh public keys can easily be retrieved using
a URL like
In order to manage repositories over ssh, you will will have to clone them via SSH, not HTTPS.
If you already have a local clone of a repository created via HTTPS, you can switch it to SSH by following Switching remote URLs from HTTPS to SSH.
The GitHub command-line interface greatly helps with working with GitHub repositories from a terminal.
Once installed you will have to start by setting up authentication.
# Authenticate with GitHub, favor SSH protocol $ gh auth login $ gh config set git_protocol ssh
The easiest way is to do it via the GitHub CLI that will also clone it locally. But it can also be done via the web interface, using the fork button and then cloning it locally manually.
This command will fork the repository to your GitHub account and clone a local copy for you to work with.
$ gh repo fork EGI-Federation/documentation
If you want to clone an existing fork you should use:
$ gh repo clone <your_username>/documentation
If your local clone of you fork is correctly setup you should see references to the origin and upstream repositories.
$ git remote -v origin email@example.com:<your_username>/documentation (fetch) origin firstname.lastname@example.org:<your_username>/documentation (push) upstream email@example.com:EGI-Federation/documentation.git (fetch) upstream firstname.lastname@example.org:EGI-Federation/documentation.git (push)
To install npm+Node.js please check the official instructions.
Everything has been tested with Node.js 12.
The dependencies of the docsy theme can be installed as follows:
# From the root of the repository clone $ npm ci
Hugo can be installed following the official documentation.
Hugo (extended) releases can be downloaded at the Hugo releases page.
To build and run the site, from the repository root:
$ git submodule update --init --recursive --depth 1 $ hugo --minify
To launch the site locally, from the repository root:
$ hugo serve -D
The site is available locally at: http://localhost:1313/.
You should submit your patch as a git branch ideally named with a meaningful name related to the changes you want to propose. This is called a feature branch (sometimes also named topic branch). You will commit your modifications to this feature branch and submit a Pull Request (PR) based on the differences between the upstream main branch and your feature branch.
Try to avoid committing changes to the main branch of your clone to simplify management, creating a dedicated feature branch helps a lot. Try to pick a meaningful name for the branch (my_nice_update in the example).
# This should be done from the up-to-date main branch # Read furthermore to see documentation on updating a local clone $ git checkout -b my_nice_update
Some environments may provide you plugins helping with syntax or offering a preview, they are worth checking.
It is the best practice to have your commit message have a summary line that includes the issue number, followed by an empty line and then a brief description of the commit. This also helps other contributors understand the purpose of changes to the code.
#3 - platform_family and style * use platform_family for platform checking * update notifies syntax to "resource_type[resource_name]" instead of resources() lookup * GH-692 - delete config files dropped off by packages in conf.d * dropped debian 4 support because all other platforms have the same values, and it is older than "old stable" debian release
# Select the modified files to be committed $ git add files1 path2/ # Commit the changes $ git commit -m <commit_message>
From inside a feature branch you can push it to your remote fork.
# Ask git to keep trace of the link between local and remote branches $ git push --set-upstream
Once done, the output will show a URL that you can click to generate a Pull Request (PR). Accessing GitHub upstream of forked repositories may also propose you to submit a PR.
If needed GitHub CLI can also be used to prepare the PR:
$ gh pr create <your_username>:<feature_branch> --web
If a repository maintainer adds the label
safe for preview to a pull request
it will be possible to preview it using a pull request-specific URL:
The preview can be used as an alternative to testing a pull request locally, and the preview can easily be shared with other contributors.
Only collaborators having write permission to the repository are able to mark a pull request as safe for review.
This should be carefully considered, especially for external and first time contributors.
Once you PR have been opened it will be reviewed, and reviewers can propose and commit changes to your PR. If you need to make further changes be sure to update the local clone with the remote changes.
# Retrieve changes made on your PR in the upstream repository $ git pull
Then you can commit new changes and push them to your remote fork.
# If you are still in a branch created for a previous PR, move to main $ git checkout main # Get the latest data from the upstream repository $ git fetch upstream # Update your local copy with this data $ git rebase upstream/main main # Update your remote GitHub fork with those changes $ git push
In case the main branch evolved since the feature branch was created, it may be required to merge the new changes in the feature branch.
It can easily be done via the PR page on the GitHub web interface, but it can
also be done in your repository clone using
# Retrieve changes made in the upstream repository $ git fetch upstream # Check out the feature branch $ git checkout feature_branch # Apply the new changes on main to your feature branch $ git rebase upstream/main
In case some files have been changed on both sides you will will have to merge the conflicts manually.
It’s possible to clone a Pull Request to a local branch to test it locally. It’s done using the PR number.
# List available PR and their identifiers. $ gh pr list # Clone specific PR, updating sudmodules $ gh pr checkout XX --recurse-submodules
Once done it’s possible to build and run the site locally:
# From the root of the repository clone # Here on MacOS X, adapt depending on your platform $ hugo serve -D
The documentation will then be accessible on http://localhost:1313.
People having write access to the repository hosting the branch related to the PR (ie. usually the PR author) will be able to add and edit files.
# From the local clone of the repository $ gh pr checkout XXX --recurse-submodules $ vim yyy.zz $ git add yyy.zz $ git commit yyy.zz -m <commit_message> $ git push
# It will ask you to merge changes $ git pull
Then you can refer to the
README.md to see how to test it locally.
In case you have troubles updating the local clone, as it can happens if changes were forced pushed to it, it maybe easier to delete the local copy of the PR and recreate it.
# Switch to main branch $ git checkout main # Check local branches $ git branch -vv # Delete a specific branch $ git branch -d <branch_name> # If you need to force the deletion use -D $ git branch -D <branch_name>
Sometimes we realise just before committing a change that we are not in the
correct branch (ie. that we forgot to create a dedicated feature branch), when
git stash can be helpful.
# Saving a change $ git stash save <optional message> # Creating the forgotten branch $ git checkout -b <my_feature_branch> # Reviewing the saved changes, use TAB completion $ git stash show <TAB> # Applying the saved changes, use TAB completion $ git stash pop <TAB> # Review the changes to be committed $ git diff
If you already committed your change(s) you may have to look at
# Viewing the diff of the two last commits $ git log -n 2 -p # Reverting the last change, keeping the change in the local directory $ git reset HEAD^