Thanks for your interest in contributing to
Our community values contributions of all forms and seeks to expand the meaning of the word "contributor" as far and wide as possible. Our contributing page gives an overview of some different ways to get involved and contribute. For technical contributions, read on to get started.
Repository file structure
envd source code lives in github.com/tensorchord/envd. Besides this, the documentation source code lives in github.com/tensorchord/envd-docs.
There are a lot of files here! Here's a brief overview. It can be confusing, but you don't need to understand every file in the repository to get started. We recommend beginning in one area (for example, adding a new function in
envd), and working your way outwards to exploring more.
- 📁 base-images/ contains Dockerfiles and build scripts of the base images used in envd.
- 📁 cmd/ contains the command line interface
- 📁 envd/ the main command line interface.
- 📁 envd-sshd/
envd-sshdwill not be used directly by envd users. It will be injected into the environment to set up the sshd.
- 📁 docs/ does not actually contain docs! Rather, it contains the proposals or static assets used in
README.md. The docs lives in github.com/tensorchord/envd-docs.
- 📁 envd/ contains a fake python package which is only used to generate
envdAPI reference. You do not need to take care of it if you do not change the
- 📁 examples/ contains some examples of
- 📁 pkg/ contains the implementation of
envdcommand line interface.
- 📁 app/ contains the command line interface configuration.
- 📁 autocomplete/ contains bash and zsh completion code for the command line interface.
- 📁 builder/ contains the buildkit builder, which is one of the most important parts. The builder compiles starlark to buildkit LLB, then builds the image.
- 📁 buildkitd/ contains the client code to connect to the buildkitd container.
- 📁 config/ contains the
- 📁 docker/ contains the client code to docker daemon.
- 📁 editor/ contains vscode or jupyter related implementation.
- 📁 envd/ contains the
envdengine, which is the abstraction to manage
- 📁 flag/ contains the information of viper flags.
- 📁 home/ contains the code to manage XDG directories (e.g.
- 📁 lang/ contains the build language code. If you want to add a new function to envd, you need to update this package.
- 📁 progress/ contains the build progress output code. You do not need to take care of it most of time.
- 📁 remote/ contains sshd implementation. You do not need to take care of it most of time.
- 📁 shell/ contains zsh-related code.
- 📁 ssh/ contains a ssh client which is used to attach to the container when running
- 📁 types/ defines some types used in 📁 pkg/envd.
The steps below walk you through the setup process. If you have questions, you can ask on discord or post an issue that describes the place you are stuck, and we'll do our best to help.
- Install Docker (20.10.0 or above) and Golang (1.18 or above).
- Fork the
envdrepository into your own GitHub account. (Remember to uncheck the "Copy the
- Clone your new fork of the repository from GitHub onto your local computer.bash
$ git clone https://github.com/YOUR_USERNAME/envd.git # or using gh CLI (this will help you set up the upstream automatically) $ gh repo clone YOUR_USERNAME/envd
- Install the dependencies and compile
envd. Make sure you can get the correct version from git tags.bash
$ go mod tidy $ make $ ./bin/envd bootstrap $ ./bin/envd version
- Make some changes locally to the codebase and commit them with Git.bash
$ git checkout -b NEW_BRANCH_NAME $ git add -u $ git commit -s -m "YOUR COMMIT MESSAGE"
- Push your new changes to your fork on GitHub.bash
$ git config --global --add --bool push.autoSetupRemote true $ git push
- Create a Pull Request on the GitHub repo page.
- PR title should start with
refactoretc., following the Conventional Commits spec.
- Describe the purpose of this PR, link to the relevant issue.
- Invite the owner to review your PR.
- PR title should start with
You could run the command below
You should see output similar to the following if there is any linting issue:
cmd/envd/main.go:36:67: Revision not declared by package version (typecheck) fmt.Println(c.App.Name, version.Package, c.App.Version, version.Revision) ^ make: *** [Makefile:102: lint] Error 1
To run tests you can issue
Debug with VSCode
envd up from a developer's perspective
envd interprets all statements in
build.envd and executes
build(). The function calls such as
config.jupyter register information to envd's in-memory static graph. Then
envd constructs the buildkit LLB DAG graph according to the information and uses it to build resulting image.
GitHub Issue Flow
- Issues tagged as
good first issue 💖are a good place to get started.
- If you'd like to start working on an existing issue, comment on the issue that you plan to work on it so other contributors know it's being handled and can offer help.