Epic: Improve Community Contributor Experience

[gtsiolis]

This epic is a placeholder that captures the improvements we'd like to do as part of making it easier for everyone to contribute to Gitpod.

Objective 🥅

Guide community contributors step-by-step from opening a pull request to merging a contribution, while leveraging a combination of automation (see gitbot, etc) and interactions with the Gitpod team members that would streamline the community contribution process.

Problem to solve ❗

1. Docs: There's no CONTRIBUTING.md file for the main repository (gitpod-io/gitpod) and this makes it difficult to discover how and where one can start for contributing to Gitpod.
2. Welcoming: Even if someone jumps right into opening a pull request for fixing a bug or a typo, there's no welcoming message that describes the process or where to reach out for getting help, a code review, or forwarding the contribution to the right team.
3. Preview Environments: There's a security risk in providing everyone access to the same clusters that handle preview environments for the Gitpod team. This is a common issue with other similar projects and communities like GitLab.
4. DRIs: Incoming community contributions can sometimes go unnoticed for longer periods as there are no DRIs (Directly Responsible Individuals) for helping with community contributions. See https://github.com/pulls?q=is%3Aopen+is%3Apr+archived%3Afalse+label%3A%22community-contribution%22+user%3Agitpod-io+.
5. Labels and Workflows: Introducing appropriate labels and triage automations that surface community contributions or looping in appropriate team members to help out is needed in order to improve visibility of PRs and scale how we handle incoming community contributions in the long run.
6. Contributor License: All contributions subject to the CLA (Contributor License Agreement). Individual contributions are subject to the Individual CLA while corporate contributions are subject to the Corporate CLA. However, signing the CLA is a) still a manual process as it requires back and forth between team members and the community contributor and b) not visible to other team members that may want to merge a contribution.

Proposal 🗺️

The following items contain a brief overview of ideas that have been discussed before and could potentially improve the community contributor experience for Gitpod as a first iteration. Thanks everyone for opening the associated issues linked below.

• [x] 1. Introduce a basic CONTRIBUTING.md doc that guides community member on how to contribute using minikube, a tool that lets you run Kubernetes locally. See https://github.com/gitpod-io/gitpod/issues/5258.
• [ ] 2. Document the areas someone can contribute to. This could include highlighting the main repository, documentation, template projects, and more. See https://github.com/gitpod-io/gitpod/issues/5618.
• [ ] 3. Introduce a welcoming messaging that is automatically posted on community contributions (PRs). This could include how and where to ask for help, etc.
• [ ] 4. Improve PR visibility for community contributions. The first iteration of this could include automatically adding the "community contribution" label on PRs from community contributors. See https://github.com/gitpod-io/gitbot/issues/34.
• [ ] 5. Investigate if it's possible and secure to give access to preview environments to community contributors by separating preview environments from the werft cluster. See https://github.com/gitpod-io/security/issues/9 (internal).
• [ ] 6. Automate CLA signing from individuals and corporations to limit back and forth between team members and community contributors regarding CLA. See https://github.com/gitpod-io/gitpod/pull/6318 and https://github.com/gitpod-io/ops/issues/130 (internal).
• [ ] 7. Add contributing guidelines with a local kubernetes cluster or minikube. See https://github.com/gitpod-io/gitpod/issues/6563.
• [ ] 8. Create a way to install a basic version of self-hosted Gitpod on a local machine for trial purposes. See https://github.com/gitpod-io/gitpod/issues/9075.

Next steps

Next steps ideas could include:

1. Introducing a volunteer role for our team that is responsible for helping contributors to get their pull requests to meet some contribution acceptance criteria, help find and assign pull requests to available reviewers, pick up and finish stale contributions, and more.
2. Automatically forwarding new PRs from the community internally in dedicated slack channel(s) to improve PR visibility within the team.
3. Regularly surface pending or stale community contributions internally in dedicated slack channel(s) to improve PR visibility within the team.
4. Now that the new product engineering structure is in place and we do automatically associate team labels in PRs[1], each team could document a process for going through community PRs.
5. ...

[svenefftinge]

Thanks, George, this is great!

I believe contributing should work self-served instead of applying and waiting for getting access to our infrastructure. I think @iQQBot has a local setup using minikube. With a streamlined installation, a self-hosted instance on my own machine or cloud should be a great preview environment. @iQQBot can you maybe write down the steps to get to such a dev environment? 🙏

Now that the new product engineering structure is in place and we do automatically associate team labels in PRs[1], each team could document a process for going through community PRs.

I don't think we have so many contributions that we need to handle it in a different process. Instead, teams should regularly check all pending PRs that have their team label, no matter the PR is from a team member another team, or a contribution.

[iQQBot]

@svenefftinge I'm currently using a standard local kubernetes cluster for gitpod development, but I'd love to try using minikube and write down the steps. However, it will take some days, and I am not good at English 😂, I hope to get your guidance in writing the documentation.

[svenefftinge]

@iQQBot cool! 🎉 It's not about minikube, even better if you use a standard kubernetes cluster. Also, we are happy to help, if you could just write down the steps someone can verify them and streamline the docs.

[iQQBot]

@roboquat doesn't work?

[aledbf]

/this-is-fine

[aledbf]

/this-is-fine

[gtsiolis]

@roboquat doesn't work?

@iQQBot yes, we've noticed some commands don't work and the team is currently working on resolving this.

🍊 🍊 🍊 🍊

❓ question: Were you trying to assign this issue to yourself?

💭 suggestion: Since this issue serves as an epic with sub-tasks related to community contributor experience that also includes tasks for team members like [5] and [6] from the proposal section in the issue description, it could be best if we split out tasks and work with the smaller issues instead. What do you think? We could open a new separate issue for everything related to setting up minikube or a local kubernetes cluster.

[iQQBot]

Sure, it would be nice, I deleted assign comment

[aledbf]

/this-is-fine

[gtsiolis]

It's ok @iQQBot! No need to delete any comments! 🙂

FYI, Added another task in the proposal of this issue (epic) and opened #6563:

7. Add contributing guidelines with a local kubernetes cluster or minikube. See Add contributing guidelines with a local kubernetes cluster or minikube #6563.

Let's continue the discussion about the local kubernetes cluster or minikube setup in #6563! 🏀

[loujaybee]

Great job on the write-up here @gtsiolis !

Came here to note that also from a priority / value point of view that having better contribution paths is a benefit to a lot of companies looking to assess and adopt Gitpod.

See: Internal Discussion

[anbraten]

This is a short list on the steps I did to setup a test cluster and try out my changes (#80). Maybe it helps you to create some contribution guide. Greets from Kiel

Building

• login to docker by using docker login [registry-url]
• build a component and the corresponding container image of Gitpod by running a commnad like (open the Gitpod repo in Gitpod itself to directly get access to all build tools): leeway build components/server:docker -DimageRepoBase=my-docker-registry-account -Dversion=my-test-version-1 or leeway build components/dashboard:docker -DimageRepoBase=my-docker-registry-account -Dversion=my-test-version-1

Deploying & testing

• create a (test) cluster and switch kubectl context to it
• add host entries on your local machine for *.gitpod.test, gitpod.test and *.ws.gitpod.test to 127.0.0.1 (/etc/hosts for linux)
• create a namespace:

  kubectl create ns gitpod

• deploy cert-manager to cluster:

  kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.7.1/cert-manager.yaml

• create custom certificates with mkcert and add CA for local testing:

  mkcert -install
  
  BASE_DOMAIN="gitpod.test"
  mkcert -key-file gitpod-key.pem -cert-file gitpod.pem $BASE_DOMAIN "*.$BASE_DOMAIN" "*.ws.$BASE_DOMAIN"
  kubectl -n gitpod create secret tls https-certificates --key=gitpod-key.pem --cert=gitpod.pem

• set node labels to match requried taints (not the best idea to set it to all nodes, but simple for testing):

  NODE=($(kubectl get node --output=name | cut -d / -f 2))
  for i in "${NODE[@]}" ; do
   echo "Set gitpod node affinities for node $i"
   kubectl label node $i gitpod.io/workload_meta=true
   kubectl label node $i gitpod.io/workload_ide=true
   kubectl label node $i gitpod.io/workload_workspace_services=true
   kubectl label node $i gitpod.io/workload_workspace_regular=true
   kubectl label node $i gitpod.io/workload_workspace_headless=true
  done

• use gitpod-install to create config:

  gitpod-installer init > gitpod.config.yaml

• adjust gitpod.config.yaml to needs and set domain to gitpod.test
• use gitpod-install to validate and create Kubernetes manifests:

  gitpod-installer validate config --config gitpod.config.yaml
  gitpod-installer render --config gitpod.config.yaml --namespace gitpod > gitpod.yaml

• adjust Kubernetes manifests if needed and set for example a specific image if you want to test a component you built yourself before (search for a string like image: eu.gcr.io/gitpod-core-dev/build/eu.gcr.io/gitpod-core-dev/build/dashboard ...
• deploy the Kubernetes manifest file with: kubectl apply -n gitpod -f gitpod.yaml
• access the test environment at https://gitpod.test

Telepresence

Telepresence allows to replace a component in your test cluster (like for example the dashboard or server) with a locally (probably inside your gitpod workspace) running instance.

To get telepresence up and running you have to do some steps:

• write your own kubernetes config into ~/.kube/config of the gitpod workspace you are using for development

  rm ~/.kube/config
  nano ~/.kube/config

• set gitpod to the default namespace (if used before as well):

  kubectl config set-context --current --namespace=gitpod

• setup telepresence

  telepresence

• start a component and replace the one running inside the cluster with your local instance

  leeway run components/server:telepresence
  # or
  leeway run components/dashboard:telepresence
  # or ... (you probably got the idea)

TODO

• run server with telepresence in watch / hot-reload mode

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.