👾 🎉 Thank you for contributing to the Hub23-deploy repository! 🎉 👾
The following is a set of guidelines for contributing to Hub23, the Alan Turing Institute's private BinderHub instance. These are mostly guidelines, not rules. Use your best judgement and feel free to propose changes to this document in a Pull Request.
Table of Contents:
- 💜 Code of Conduct
- ❓ What do I need to know?
- 🎁 How can I contribute?
- 🎨 Styleguides
- 📓 Additional Notes
Everyone participating in this project is expecting to abide by and uphold our Code of Conduct. Please report any unacceptable behaviour to Dr Sarah Gibson.
Hub23 is a BinderHub instance. BinderHub is computational infrastructure that makes sharing reproducible computational environments and analyses in the cloud as simple as clicking a link in your browser. Sarah has given many talks on what Binder/BinderHub/mybinder.org is and how it works, so for the sake of brevity we'll just focus on Hub23 here.
Hub23 was set up to provide members of the Turing with an alternative to the public BinderHub, mybinder.org, which allows for authenticating users. Eventually we also hope to support private code repositories and datasets.
Hub23 got it's name as a derivative of the Research Engineering team's nickname Hut23, which derives from the hut that housed the engineering team at Bletchley Park during World War Two. This, of course, was where Alan Turing and his team cracked the German Enigma code.
Hub23 is deployed on a Kubernetes cluster. This allows for effective and efficient scaling in response to demand.
This repository (https://github.com/alan-turing-institute/hub23-deploy) houses the Helm chart, a YAML formatted set of instructions to Kubernetes on how to deploy and configure the resources and services to run BinderHub.
This chart is located in the hub23-chart folder and the deployment configuration is stored in deploy.
The Hub23 Helm chart is dependent on a range of other published Helm charts:
- BinderHub: The main software
ingress-nginx: To monitor traffic from the internet and outside sources
These charts are also under active development and regularly updated, so how do we make sure Hub23 is running the latest version? With a bot of course!
The bump-helm-deps-action GitHub Action regularly checks the Helm chart version we're running against the published versions.
If it finds a newer version, the bot will open a Pull Request updating Hub23's requirements.yaml file with the most up-to-date versions.
Providing the tests pass on the Pull Request, these are generally safe to merge.
The front page of the Hub23 site is described by HTML stored in the templates directory.
Any additional images (such as logos) are kept in the static directory.
These templates extend the BinderHub web framework that ships with the BinderHub Helm chart.
This repository uses an Azure Pipeline to keep the Hub23 deployment up-to-date with the main branch of this repository. Any push to the main branch (such as merging a Pull Request) will trigger the pipeline and upgrade the deployment with any changes implemented in the Helm chart.
🚨 It is therefore strongly recommended that developers avoid manually upgrading the deployment. Instead, please use a Pull Request that can be reverted if needed. This will help maintain a consistent state of the deployment. 🚨
Kubernetes resources and Helm charts are compromised of YAML files. Unfortunately, Helm is sensitive to malformed YAML files but fails silently during an upgrade if such a file is found. Therefore, there is a validation pipeline implemented on the repository which runs in all Pull Requests to main branch. This verifies that the helm chart is well-formed and can be understood by Kubernetes and Helm when applied.
An Azure Pipeline runs a nightly check to see if the deployment subscription is still active. The most likely cause for the subscription to be disabled is lack of funds and all resources will be unreachable during this time.
The Hub23 Deployment Guide is written in Markdown files kept in the docs/_posts folder.
These are then rendered using Jupyter Book and GitHub Pages and served at alan-turing-instutite.github.io/hub23-deploy.
- Billing: There is a Python script under
billingthat helps calculate running costs for the deployment. If the subscription runs out of funds, a request for more credits should be filed on Turing Complete (TopDesk).
If something doesn't work the way you expect it to, please check it hasn't already been reported in the repository's issue tracker.
Bug reports should have the [bug label](is:issue is:open label:bug), or have a title beginning with [BUG].
If you can't find an issue already reporting your bug, then please feel free to open a new issue. This repository has a bug report template to reports be as descriptive as possible so we can squash that bug! 💪
If there is something extra you wish Hub23 could do, please check that the feature hasn't already been requested in the project's issue tracker. Feature requests should have the enhancement label. Please also check the closed issues to make sure the feature has not already been requested but the project maintainers decided against developing it.
If you find an open issue describing the feature you wish for, you can "+1" the issue by giving a thumbs up reaction on the top comment. You may also leave any thoughts or offers for support as new comments on the issue.
If you don't find an issue describing your feature, please open a feature request. This repository has a feature request template to help map out the feature you'd like.
A Pull Request is a means for people to collaboratively review and work on changes before they are introduced into the base branch of the code base.
To prepare your contribution for review, please follow these steps:
- Fork this repository
- Create a new branch on your fork
- Where possible and appropriate, please use the following convention when naming your branch:
<type>/<issue-number>/<short-description>. For example, if your contribution is fixing a a typo that was flagged in issue number 11, your branch name would be as follows:fix/11/typo.
- Where possible and appropriate, please use the following convention when naming your branch:
- Edit files or add new ones!
- Open your Pull Request
- This repository has a pull request template which will help you summarise your contribution and help reviewers know where to focus their feedback. Please complete it where possible and appropriate.
Congratulations! 🎉 You are now a Hub23 developer! 👾
The project maintainers will then review your Pull Request and may ask for some changes. Once you and the maintainers are happy, your contribution will be merged!
When writing Python scripts for this repository, it is recommended that contributors use black and flake8 for formatting and linting styles.
The repository uses pre-commit to automatically ensure code adheres to these guidelines.
These tools are used as the maintainers believe this makes the code easier to read and keeps consistent formatting as more people contribute to the project.
While flake8 commands can be disabled, we only recommend doing this for specific lines in such cases where reformatting would produce "ugly code". The maintainers retain final say on what is "ugly code" on a case-by-case basis.
Documentation files are written in Markdown.
When writing Markdown, it is recommended to start a new sentence on a new line and define a new paragraph by leaving a single blank line. (Check out the raw version of this file for an example!) While the sentences will render as a single paragraph; when suggestions are made on Pull Requests, the GitHub User Interface will only highlight the affected sentence - not the whole paragraph. This makes reviews much easier to read!
Issues and Pull Requests can have labels assigned to them which indicate at a glance what aspects of the project they describe. It is also possible to sort issues by label making it easier to track down specific issues. Below is a table with the currently used labels in the repo.
| Label | Description |
|---|---|
bug |
Something isn't working |
documentation |
Improvements or additions to the documentation |
enhancement |
New feature or request |
good first issue |
Good for newcomers |
help wanted |
Extra attention is needed |
question |
Looking for input on a topic |
wip |
Work in progress |