Contribute on GitHub
Prerequisites
If are new to GitHub, you will first need to
sign up for a GitHub account.
For learning GitHub, we also encourage you to complete
self-paced GitHub learning courses for brushing up basic GitHub skills.
Note: Please note that you do not need to complete all these learning courses before making your first contribution. The first
"Introduction to Github" course should make you well-equipped for making your first contribution to the Hive!
Let's get started!
This documentation is written in Markdown format and is based on the Material for MkDocs theme, which is built on top of MkDocs static site generator.
For a quick reference on how to use Markdown syntax you can refer to the Markdown Cheat Sheet.
Raise a GitHub Issue
All contributions need to have an associated Github issue that explains the content and importance of the contribution.
To raise an issue, create a New Issue in the ACCESS-Hive Github repository issue page. Feel free to assign that issue to yourself if you intend to work on it.
Fork the ACCESS-Hive GitHub repository
After raising a Github issue about your contribution, you need to fork the ACCESS-Hive Github repository.
Clone the forked ACCESS-Hive GitHub repository locally
For cloning the forked repository onto your local computer, we encourage you to first add your local SSH keys to your GitHub profile.
To start with, if you have an existing SSH key, then simply add this key to your github account, and you are all set to clone the repository. In case you don't have the SSH keys set up on your local computer, it's easy to create a new SSH key locally, and then feel free to link this key to your github account.
git clone git@github.com:ACCESS-Hive/access-hive.github.io.git
Cloning into 'access-hive.github.io'...
remote: Enumerating objects: 54754, done.
remote: Counting objects: 100% (4096/4096), done.
remote: Compressing objects: 100% (560/560), done.
remote: Total 54754 (delta 2178), reused 4053 (delta 2155), pack-reused 50658
Receiving objects: 100% (54754/54754), 103.15 MiB | 6.97 MiB/s, done.
Resolving deltas: 100% (28610/28610), done.
Make changes locally
After cloning the repository locally, create a new branch to make your local changes and then push it to GitHub:
git checkout -b spongebob/fix-hive-title-issue-234
Switched to a new branch 'spongebob/fix-hive-title-issue-234'
git push --set-upstream origin spongebob/fix-hive-title-issue-234
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a pull request for 'spongebob/fix-hive-title-issue-234' on GitHub by visiting:
remote: https://github.com/ACCESS-Hive/access-hive.github.io/pull/new/spongebob/fix-hive-title-issue-234
remote:
To github.com:ACCESS-Hive/access-hive.github.io.git
* [new branch] spongebob/fix-hive-title-issue-234 -> spongebob/fix-hive-title-issue-234
branch 'spongebob/fix-hive-title-issue-234' set up to track 'origin/spongebob/fix-hive-title-issue-234'.
Work locally on the branch spongebob/fix-hive-title-issue-234
, and push the commits using the commands:
git add .
git commit -m "(#234) Fixed Hive title!"
[spongebob/fix-hive-title-issue-234 7afe8c11] (#234): Fixed Hive title!
1 file changed, 17 insertions(+)
git push
Enumerating objects: 11, done.
Counting objects: 100% (11/11), done.
Delta compression using up to 10 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 637 bytes | 637.00 KiB/s, done.
Total 6 (delta 5), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (5/5), completed with 5 local objects.
To github.com:ACCESS-Hive/access-hive.github.io.git
7263feb5..7afe8c13 spongebob/fix-hive-title-issue-234 -> spongebob/fix-hive-title-issue-234
While working on a local branch, please make sure to regularly pull changes from the remote main
into your local branch, as follows:
git pull origin main
From github.com:ACCESS-Hive/access-hive.github.io
* branch main -> FETCH_HEAD
Already up to date.
This would make sure that the local branch spongebob/fix-hive-title-issue-234
is always in sync with the latest changes in the remote main
branch.
Deploying Website Preview
MkDocs includes a live preview server, so you can preview your changes as you write your documentation. The server will automatically rebuild the site upon saving.
To build the site locally, you need to install Material for MkDocs and other plugins. You can find a ful list in the requirements.txt
file (in the root of the ACCESS-Hive GitHub repository). Please use pip
for the installation as some of the packages are not updated or not available on conda:
pip install -r requirements.txt
To start the server, open terminal and navigate to your ACCESS-Hive local repository and use the command:
mkdocs serve
INFO - Building documentation...
INFO - [macros] - Macros arguments: {'module_name': 'main', 'modules': [], 'include_dir': '', 'include_yaml': [], 'j2_block_start_string': '', 'j2_block_end_string': '',
'j2_variable_start_string': '', 'j2_variable_end_string': '', 'on_undefined': 'keep', 'on_error_fail': False, 'verbose': False}
INFO - [macros] - Extra variables (config file): ['generator', 'social', 'analytics']
INFO - [macros] - Extra filters (module): ['pretty']
INFO - Cleaning site directory
INFO - Documentation built in 12.33 seconds
INFO - [09:19:05] Reloading browsers
INFO - [09:19:05] Browser connected: http://127.0.0.1:8000/about/contribute/contribute_on_github/
Your documentation will be built on http://127.0.0.1:8000. Open this URL in your browser to see a preview of the documentation. The URL is given in the terminal when running the mkdocs serve
command. Make sure you keep the command running so as to see live updates on saving your modifications.
Create a Pull Request for the final changes
Once the changes on your local branch spongebob/fix-hive-title-issue-234
are ready to be integrated with the development
branch, create a pull request and GitHub will automatically build a preview of the documentation using GitHub Actions.
Note: It can take a while for the preview to build, even after the CI check is indicated as "finished". Please wait for the comment with the link to appear and allow for some time after that for the preview to be properly deployed.
If you open the preview and it looks completely broken or if it hasn't updated from additional modifications in the pull reuqest, it probably means the site hasn't finished building yet. If you wait a couple of minutes and refresh the page, it should fix itself.
After a PR is created and tested, feel free to ask for reviews by tagging the ACCESS-Hive/reviewers team and reply if any changes are being requested in the PR.
Additional GitHub learning resources
Last update:
April 25, 2024