# Drafting a JupyterHub Contributor Onboarding Landing Page

_The idea with this work is to create a contributor landing page that tries to pull together key areas of JupyterHub Documentation and the Team Compass to invite new contributors, give them a sense of the project, and support and challenge them to setup a development environment (if they have dev interest._

# Welcome to the Jupyter Hub: Contributor Onboarding Guide

Welcome to JupyterHub! This guide will help you get started as a contributor through a series of self-paced activities. By the end, you'll have a good understanding of the project, how to contribute, and how to engage with our community.

JupyterHub is a multifaceted piece of infrastructure which can be used in many ways. It is used in academic institutions as a key piece of infrastructure to bring interactive computing environments to learners.

These can be Jupyter Notebooks, RStudio Sessions, marimo, etc., or any interactive web page environment. While it doesn't have to be run with kubernetes, you'll find many production deployments use kubernetes. JupyterHub is a low-level piece of critical infrastructure for many large scale computational learning environments worldwide.

JupyterHub is also a collection of opinionated distributions of this infrastructure, for example [Zero to JupyterHub with Kubernetes](https://z2jh.jupyter.org/) and [The Littlest JupyterHub](https://tljh.jupyter.org/). If you have needs for bringing web-based interactive computing services to your learners, JupyterHub might be the right piece of kit for you. JupyterHub also provides the foundation for the [mybinder.org](https://mybinder.org/) ad hoc Jupyter environment service.

## Step 1: Understand Our Mission and Vision

- Read our [Project Overview](https://jupyterhub.readthedocs.io/en/stable/index.html) 
- **Activity:** Reflect on how our mission aligns with your interests and goals, share those reflections in your "Hello Jupyter Hub" note (Template Below)
- **Activity:** Familiarize yourself with JupyterHub [(the software) documentation](https://jupyterhub.readthedocs.io) and JupyterHub (the project) documentation [called the Team Compass](https://jupyterhub-team-compass.readthedocs.io)

## Step 2: Read Case Studies and see how people are using JupyterHub

- See how others are deploying [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/reference/gallery-jhub-deployments.html) in our Gallery of Deployments
- **Activity:** Have a read through the case studies and see the many ways JupyterHub is enabling learning, science and creativity globally.

## Step 3: Set Up Your Environment and/or deploy your first JupyterHub

The first thing you should do is to determine what *type* of JupyterHub deployment will eventually meet your requirements:

- [The Littlest Jupyterhub](https://tljh.jupyter.org/en/latest/index.html) is useful in a small-scale setting, with few users and running on bare metal or a VM. For instance, in a small research setting with a few collaborators. It is not appropriate for larger (multiple tens or more users), long running and scalable deployments.

- [Zero to Jupyterhub](https://z2jh.jupyter.org/) allows better handling of authentication, scaling for many users, and runs natively on kubernetes. This type of deployment would be appropriate for larger institutions that will be running Jupyterhub as a service, like in an educational, large-scale reserarch or enterprise setting with a dedicated SRE team.

- [JupyterHub the Hard Way](https://github.com/jupyterhub/jupyterhub-the-hard-way/tree/master) will have you deploy a JupyterHub from scratch, and give you a sense of the various parts of JupyterHub and how they interconnect. This resource explains the various components of JupyterHub and takes you through the manual process of interconnecting them. As you step through JupyterHub the hard way, submit any issues or challenges you encounter to the repo as issues (bugs) or pull requests (fixes). This is more useful as a learning tool, rather than the base for a long-running deployment.

Even if you're planning on a larger, Zero to Jupyterhub deployment, it might make sense to spin up Option 1 (The Littlest JupyterHub) to get a feel for how things are deployed.

Since there are many ways to deploy JupyterHub, from bare metal to kubernetes in the cloud, each with different tradeoffs and capabilities, we also recommend perusing the [Technical Overview](https://jupyterhub.readthedocs.io/en/stable/reference/technical-overview.html) to start.

### Option 1 - Deploy The Littlest JupyterHub

_If you're interested in installing or administering a JupyterHub the Littlest JupyterHub will help you stand up your first JupyterHub and get to know what is possible!_

- Explore [The Littlest JupyterHub](https://tljh.jupyter.org/en/latest/index.html)
- **Activity:** Try to deploy your first Littlest JupyterHub. A good first platform option is a VM on Google Cloud, as it will provide you with free credits to deploy your first Littlest JupyterHub. While the overall layout of Google Cloud is subject to constant change, you should be able to deploy your first hub within 30 mins. Feel free to play with the many options, and look them up if you are unfamiliar with them.

### Option 2 - Deploy Z2JH

_This option is for a user familiar with Kubernetes and perhaps a regular user of Kubernetes. It can help you get-started with JupyterHub. If you're not familiar with Kubernetes then Option #1 or #3 are probably better suited._

- Explore [Zero to JupyterHub](https://zero-to-jupyterhub.readthedocs.io/en/latest/)
- **Activity** Create a k8s cluster on the platform of your choice (bare-metal or cloud), and deploy Zero to JupyterHub to that kubernetes cluster as a Helm chart.

### Option 3 - Development Environment Setup

_If you're interested in making development contributions, this will help you get started._

- Follow our [Development Environment Setup Guide](https://jupyterhub.readthedocs.io/en/latest/contributing/setup.html) (15-20 minutes)
- Run the test suite in your environment.
- Work through [JupyterHub The Hard Way](https://github.com/jupyterhub/jupyterhub-the-hard-way/tree/master) with the various components.
- **Activity:** Submit a PR to the Development Environment Setup Guide page for any setup problems you encounter in your environment.

## Step 4: Explore the Codebase and Team Compass

- Review our [Technical Overview](https://jupyterhub.readthedocs.io/en/stable/reference/technical-overview.html) 
- Familiarize yourself with the [Team Compass](https://compass.hub.jupyter.org/), our way of articulating how our community tries to "sail together". Notable sections to review are [Policies and Standards](https://compass.hub.jupyter.org/index-team_policies/) and our articulation of [Team Responsibilities](https://compass.hub.jupyter.org/team/structure/#expectations-of-all-team-members).

## Step 5: Understand the Contribution Process

- Read our [Contributing Guide](https://jupyterhub.readthedocs.io/en/stable/contributing/index.html)
- **Challenge:** Identify one area where you think you could contribute to improve JupyterHub (code, documentation, testing, design, etc.) and add it to your introduction on Zulip

## Step 6: Engage with the Community

- Join our [Zulip Chat](https://jupyter.zulipchat.com/#narrow/channel/469744-jupyterhub) and introduce yourself
- Check out the Jupyter Forum (https://discourse.jupyter.org/) and [Jupyter Hub Category](https://discourse.jupyter.org/c/jupyterhub/10) on the forum. Review a few of the recent posts and familiarize yourself with the community and its conversations.
- Attend a community meeting (schedule in [Team Compass](https://compass.hub.jupyter.org/meetings/))
- Have a look at open issues on [jupyterhub/jupyterhub](https://github.com/jupyterhub/jupyterhub/issues) or [jupyterhub/team-compass](https://github.com/jupyterhub/team-compass)
- Attend a community collaboration café (schedule in Team Compass, [Jupyter Community Calendar](https://discourse.jupyter.org/t/jupyter-community-calendar/2485))

## Step 7: Make Your First Contribution

_As you test out howtos and tutorials, or use the documentation, we welcome contributions which update or fix issues you find in the docs._

- Going through the documentation and [Team Compass](https://github.com/jupyterhub/team-compass), have you found anything that needs updating / improving?
- Follow our [Step-by-Step Contribution Guide](https://jupyterhub.readthedocs.io/en/stable/contributing/index.html) to submit your first pull request

## Additional Resources

- [Reference Docs](https://jupyterhub.readthedocs.io): Learn about the technical capabilities
- [Team Compass](https://compass.hub.jupyter.org/): Learn about our community structure and governance
- [Code of Conduct](https://jupyter.org/governance/conduct/code-of-conduct/): Understand our community standards
- [Project Roadmap](https://jupyterhub.readthedocs.io/en/stable/contributing/roadmap.html): See where we're headed and how you can help

## Engagement Checklist

If you're excited about our project and want to stay involved, here are some next steps:
- [ ] Attend a JupyterHub Collaboration Café meeting (schedule in [Team Compass](https://compass.hub.jupyter.org/meetings/))
- [ ] [Browse and subscribe to JupyterHub's Discourse](https://discourse.jupyter.org/c/jupyterhub/)
- [ ] Subscribe to the [Project Jupyter Zulip](https://jupyter.zulipchat.com/) and [#jupyterhub](https://jupyter.zulipchat.com/#narrow/channel/469744-jupyterhub) Channel for project updates and introduce yourself
- [ ] Complete your first documentation [pull request](https://jupyterhub.readthedocs.io/en/stable/contributing/docs.html)
- [ ] Become familiar with contributor guide
- [ ] Help another new contributor in the forums or Zulip channel

Remember, contribution isn't just about code. Documentation, testing, design, and community support are all valuable ways to contribute!

We're thrilled to have you join us! If you have any questions along the way, don't hesitate to ask in our community channels. Happy contributing!

#### Thanks to

@rgaiacs, @manics, @shaneknapp, @minrk, @jduckles, @Arielle-Bennett, @ryanlovett, @aprilmj, @stebo85, @kellyrowland, @bduckles and @KirstieJane for help with this page.

#### CONTRIBUTING.md

Welcome! As a [Jupyter](https://jupyter.org) project, you can follow the [JupyterHub contributor guide](https://compass.hub.jupyter.org/contribute/) for

Make sure to also follow [Project Jupyter's Code of Conduct](https://jupyter.org/governance/conduct/code-of-conduct/) for a friendly and welcoming collaborative environment.

<optional setup part>
If you are contributing code features or fixes, you will want to ensure the functionality of your work.
Here's how you set up your development environment:
<link to SETUP.md as applicable>
</optional setup part>

Please make sure you've read the following sections before opening an issue/pull request:

<update port repo2docker to main Jupyter Hub Docs - https://repo2docker.readthedocs.io/en/latest/contribute/contributing.html#process-for-making-a-contribution>
- [Process for making a contribution]()
- These steps talk you through choosing the right issue template (bug report or feature request) and making a change.
<update / port repo2docker to main Jupyter Hub Docs - https://repo2docker.readthedocs.io/en/latest/contribute/contributing.html#guidelines-to-getting-a-pull-request-merged >
- [Guidelines to getting a Pull Request merged]().
- These are tips and tricks to help make your contribution as smooth as possible for you and for the JupyterHub community.

There are a few other pages to highlight:

### [Our roadmap](https://jupyterhub.readthedocs.io/en/stable/contributing/roadmap.html)
We use the roadmap to develop a shared understanding of the project's vision and direction amongst the community of users, contributors, and maintainers. This is a great place to get a feel for what the maintainers are thinking about for the short, medium, and long term future of the project.

### [Subsystems of JupyterHub](https://jupyterhub.readthedocs.io/en/stable/#subsystems)
- This page explains some of the design principles behind JupyterHub. Its a good place to understand why the team have made the decisions that they have along the way!

### [Common developer tasks and how-tos](https://jupyterhub.readthedocs.io/en/stable/howto/index.html)
- Some notes on running tests, buildpack dependencies, creating a release, and keeping the pip files up to date.