Kaan Barmore-Genç
2d85ca331c
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
119 lines
7.1 KiB
Markdown
119 lines
7.1 KiB
Markdown
---
|
|
title: 'Adding single click dev environment links to your open source project for easy contributions'
|
|
date: 2024-05-27T05:10:06Z
|
|
description: 'See how you can streamline contributions and onboarding by leveraging DevContainers and cloud dev environments - a one-click setup that lets new folks dive right in!'
|
|
highlighted: true
|
|
---
|
|
|
|
[I have been using DevContainers](/2023.02.10.why-use-devcontainer/) a lot. If
|
|
you haven't heard about them, it's a standard for defining development
|
|
environements using container technologies. The idea is pretty simple: you
|
|
define a base container for your development environment --which can be a
|
|
special DevContainer one, or any regular old container-- along with any service
|
|
containers you need. Whenever you or anyone else needs a new development
|
|
environment, their development environment grabs and runs these docker
|
|
containers, and runs any commands you defined in the configuration to set things
|
|
up.
|
|
|
|
This comes with many benefits:
|
|
|
|
- Assuming you deploy with containers, your development environment can more
|
|
closely match your production environment.
|
|
- There are no "works on my machine" issues, everyone has the same development
|
|
environment.
|
|
- If anything goes wrong with your development environment, instead of trying to
|
|
figure out what happened, you can delete it and start over in seconds.
|
|
- You were in the middle of something, and an urgent bug came up? Instead of
|
|
trying to stash your work and clean up your environment, leave it where it is
|
|
and launch another fresh development environment and get to work.
|
|
- New contributors to your open source project, or new hires can start
|
|
developing immediately without having to set up anything, beyond installing
|
|
Docker.
|
|
|
|
The last point here is the one I want to focus on in this blog post. Especially
|
|
with open source projects, one of the biggest barriers to contribution is that
|
|
it can be hard to install and set up everything you need to contribute to a
|
|
project. Especially if you were trying to fix or add something small, it can be
|
|
harder to set up the development environment than it is to actually develop
|
|
whatever you were actually trying to do. The same issue applies for companies.
|
|
Onboarding new employees is hard. Writing good onboarding documentation and
|
|
keeping it up to date takes a lot of work. But without good documentation, new
|
|
hires have to keep bugging experienced developers so they can start working.
|
|
This slows down how soon new hires can start doing productive work, takes up
|
|
time of experienced devs, and leaves everyone frustrated.
|
|
|
|
If I have sold you on DevContainers, check out [my previous blog post](/2023.02.10.why-use-devcontainer/)
|
|
on the topic on how to get started or
|
|
[VSCode docs](https://code.visualstudio.com/docs/devcontainers/containers)
|
|
(note: DevContainers are not exclusive to VSCode, support is being added to
|
|
JetBrains products, and a CLI implementation is available as well).
|
|
Once you have your DevContainers set up though, you get an amazing opportunity to make contributions or development even easier.
|
|
Enter cloud development environments.
|
|
|
|
DevContainer support is built into [Github Codespaces](https://github.com/features/codespaces) and [CodeSandbox](https://codesandbox.io/).
|
|
These projects allow you to spin up machines in the cloud for development, and work on it through a web interface.
|
|
Combined with DevContainers, you can click one button to get a fully-fledged development environment in your web browser within seconds.
|
|
Along with these, [DevPod](https://devpod.sh) is an open source solution that you can install on your own machine,
|
|
and use with a local Docker install, remote VMs, or one of their many supported providers like AWS or Azure or DigitalOcean.
|
|
You can take advantage of this yourself by just having these services/tools clone your repository,
|
|
but we can make it even better and help newcomers by adding links to these services.
|
|
|
|
|
|
|
|
To do so, simply add the following links to your Readme, replacing `<Owner>` and
|
|
`<Repo>` with your own username and repository. Note that besides Github
|
|
Codespaces, these are not restricted to Github and
|
|
can be used with other forge services like [Gitlab](https://about.gitlab.com) or [Codeberg](https://codeberg.org).
|
|
|
|
```md
|
|
[](https://codespaces.new/<Owner>/<Repo>)
|
|
[](https://devpod.sh/open#https://github.com/<Owner>/<Repo>)
|
|
[](https://codesandbox.io/p/devbox/github/<Owner>/<Repo>)
|
|
```
|
|
|
|
Having these links in your Readme is nice, but what if we went one step further?
|
|
We could use these tools to make PR reviews easier too. You can click one button
|
|
on Github or your favorite forge to see the changes in a PR, wouldn't it be
|
|
great if you can click one button to launch a fresh development environment with
|
|
that PR? It would be, and we can do this!
|
|
|
|
To make this happen, I wrote a Github Actions workflow to post a comment to PRs
|
|
with the appropriate links. Let's see what that workflow looks like:
|
|
|
|
```yml
|
|
on: pull_request
|
|
|
|
permissions:
|
|
pull-requests: write
|
|
|
|
jobs:
|
|
comment_click_dev:
|
|
runs-on: ubuntu-latest
|
|
name: Comment Cloud Dev Buttons
|
|
steps:
|
|
- name: Comment PR
|
|
uses: thollander/actions-comment-pull-request@v2
|
|
with:
|
|
message: |
|
|
Click links below to open this PR in a dev environment:
|
|
|
|
[](https://codespaces.new/<Owner>/<Repo>/tree/${{github.head_ref}})
|
|
[](https://devpod.sh/open#https://github.com/<Owner>/<Repo>@${{github.head_ref}})
|
|
[](https://githubbox.com/<Owner>/<Repo>/tree/${{github.head_ref}})
|
|
comment_tag: comment_click_dev
|
|
```
|
|
|
|
This workflow uses [this cool action by Térence Hollander](https://github.com/marketplace/actions/comment-pull-request)
|
|
to post a comment to the PR from a workflow.
|
|
Like the Readme example, replace the `<Owner>` and `<Repo>` with your username and repository.
|
|
|
|
|
|
|
|
These work great. Whenever you're reviewing a PR, if you want to run the code or
|
|
use a more comfortable environment than Github's changes view, you can click
|
|
these buttons and get the PR in a new development environment, without having to
|
|
stash or discard anything you were already working on.
|
|
|
|
The only caveat with these links is that I couldn't figure out how to make it work for CodeSandbox without going through the `githubbox.com` URL.
|
|
This URL seems to be owned by CodeSandbox from what I gather so it's not dangerous or anything, but it limits it to repositories on Github only.
|