diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index c772a8dd068..7f24327e4ec 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,3 +1,14 @@ ## Summary ## How was it tested? + +## Community Contribution License + +All community contributions in this pull request are licensed to the project +maintainers under the terms of the +[Apache 2 License](https://www.apache.org/licenses/LICENSE-2.0). + +By creating this pull request, I represent that I have the right to license the +contributions to the project maintainers under the Apache 2 License as stated in +the +[Community Contribution License](https://github.com/jetify-com/opensource/blob/main/CONTRIBUTING.md#community-contribution-license). diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 408cceff79a..0ac263c0b1b 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -59,8 +59,8 @@ representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement. Use the -"Report to repository admins" functionality on GitHub to report. +reported to the community leaders responsible for enforcement. Use the "Report +to repository admins" functionality on GitHub to report. All complaints will be reviewed and investigated promptly and fairly. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d29c91d9758..2bee544a437 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,15 @@ # Contributing -When contributing to this repository, please describe the change you wish to make via a related issue, or a pull request. +When contributing to this repository, please describe the change you wish to +make via a related issue, or a pull request. -Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project. +Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in +all your interactions with the project. ## Setting Up Development Environment -Before making any changes to the source code (documentation excluded) make sure you have installed all the required tools. +Before making any changes to the source code (documentation excluded) make sure +you have installed all the required tools. ### With Devbox @@ -21,7 +24,8 @@ The easiest way to develop Devbox is with Devbox! git clone https://github.com/jetify-com/devbox.git go.jetify.com/devbox cd go.jetify.com/devbox -3. Build the Devbox CLI. If you don't have Nix installed, Devbox will automatically install it for you before building: +3. Build the Devbox CLI. If you don't have Nix installed, Devbox will + automatically install it for you before building: devbox run build @@ -29,18 +33,26 @@ The easiest way to develop Devbox is with Devbox! dist/devbox shell -Tip: you can also start VSCode from inside your Devbox shell with `devbox run code`. -- If you are encountering an error similar to: `line 3: command 'code' not found`, this means you do not have the Visual Studio Code "Shell Command" installed. To do this, follow the official guide: https://code.visualstudio.com/docs/setup/mac. Please refer to the section under: "Launching from the command line". +Tip: you can also start VSCode from inside your Devbox shell with +`devbox run code`. + +- If you encounter an error similar to: `line 3: command 'code' not found`, it + means you do not have the Visual Studio Code "Shell Command" installed. Follow + the official guide at https://code.visualstudio.com/docs/setup/mac. Please + refer to the section under: "Launching from the command line". ### Setting up the Environment Without Devbox -If you are unable to install or use Devbox, you can manually replicate the environment by following the steps below. +If you are unable to install or use Devbox, you can manually replicate the +environment by following the steps below. -1. Install Nix Package Manager. We recommend using the [Determinate Systems installer](https://github.com/DeterminateSystems/nix-installer): +1. Install Nix Package Manager. We recommend using the + [Determinate Systems installer](https://github.com/DeterminateSystems/nix-installer): curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install - Alternatively, you can also use [the official installer](https://nixos.org/download.html). + Alternatively, you can also use + [the official installer](https://nixos.org/download.html). 2. Install [Go](https://go.dev/doc/install) (current version: 1.20) @@ -53,29 +65,52 @@ If you are unable to install or use Devbox, you can manually replicate the envir ## Pull Request Process -1. For new features or non-trivial changes, consider first filing an issue to discuss what changes you plan on making. This will let us help you with implementation details and to make sure we don't duplicate any work. -2. Ensure any new feature or functionality includes tests to verify its correctness. +1. For new features or non-trivial changes, consider first filing an issue to + discuss what changes you intend to make. This will let us help you with + implementation details and to make sure we don't duplicate any work. +2. Ensure any new feature or functionality includes tests to verify its + correctness. 3. Run `devbox run lint` and `devbox run test`. 4. Run `go mod tidy` if you added any new dependencies. 5. Submit your pull request and someone will take a look! ### Style Guide -We don't expect you to read through a long style guide or be an expert in Go before contributing. When necessary, a reviewer will be happy to help out with any suggestions around code style when you submit your PR. Otherwise, the Devbox codebase generally follows common Go idioms and patterns: +We don't expect you to read through a long style guide or be an expert in Go +before contributing. When necessary, a reviewer will be happy to help out with +any suggestions around code style when you submit your PR. Otherwise, the Devbox +codebase generally follows common Go idioms and patterns: + +- If you're unfamiliar with idiomatic Go, + [Effective Go](https://go.dev/doc/effective_go) and the + [Google Go Style Guide](https://google.github.io/styleguide/go) are good + resources. +- There's no strict commit message format, but a good practice is to start the + subject with the name of the Go packages you add/modified. For example, + `boxcli: update help for add command`. + +## Community Contribution License + +Contributions made to this project must be made under the terms of the +[Apache 2 License](https://www.apache.org/licenses/LICENSE-2.0). + +``` +By making a contribution to this project, you certify that: -- If you're unfamiliar with idiomatic Go, [Effective Go](https://go.dev/doc/effective_go) and the [Google Go Style Guide](https://google.github.io/styleguide/go) are good resources. -- There's no strict commit message format, but a good practice is to start the subject with the name of the Go packages you add/modified. For example, `boxcli: update help for add command`. + a. The contribution was created in whole or in part by you and you have the right + to submit it under the Apache 2 License; or -## Developer Certificate of Origin + b. The contribution is based upon previous work that, to the best of your + knowledge, is covered under an appropriate open source license and you have the + right under that license to submit that work with modifications, whether + created in whole or in part by you, under the Apache 2 License; or -By contributing to this project you agree to the [Developer Certificate of Origin](https://developercertificate.org/) (DCO) which was created by the Linux Foundation and is a simple statement that you, as a contributor, have the legal right to make the contribution. See the DCO description for details below: + c. The contribution was provided directly to you by some other person who + certified (a), (b) or (c) and you have not modified it. -> By making a contribution to this project, I certify that: -> -> a. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or -> -> b. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or -> -> c. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. -> -> d. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. + d. You understand and agree that this project and the contribution are public + and that a record of the contribution (including all personal information you + submit with it, including your sign-off) is maintained indefinitely and may be + redistributed consistent with this project or the open source license(s) + involved. +``` diff --git a/README.md b/README.md index e18b0475081..2f0da16e4a1 100644 --- a/README.md +++ b/README.md @@ -8,15 +8,27 @@ ### Instant, easy, and predictable development environments -[![Join Discord](https://img.shields.io/discord/903306922852245526?color=7389D8&label=discord&logo=discord&logoColor=ffffff&cacheSeconds=1800)](https://discord.gg/jetify) ![License: Apache 2.0](https://img.shields.io/github/license/jetify-com/devbox) [![version](https://img.shields.io/github/v/release/jetify-com/devbox?color=green&label=version&sort=semver)](https://github.com/jetify-com/devbox/releases) [![tests](https://github.com/jetify-com/devbox/actions/workflows/cli-post-release.yml/badge.svg)](https://github.com/jetify-com/devbox/actions/workflows/cli-release.yml?branch=main) [![Built with Devbox](https://www.jetify.com/img/devbox/shield_galaxy.svg)](https://www.jetify.com/devbox/docs/contributor-quickstart/) +[![Join Discord](https://img.shields.io/discord/903306922852245526?color=7389D8&label=discord&logo=discord&logoColor=ffffff&cacheSeconds=1800)](https://discord.gg/jetify) +![License: Apache 2.0](https://img.shields.io/github/license/jetify-com/devbox) +[![version](https://img.shields.io/github/v/release/jetify-com/devbox?color=green&label=version&sort=semver)](https://github.com/jetify-com/devbox/releases) +[![tests](https://github.com/jetify-com/devbox/actions/workflows/cli-post-release.yml/badge.svg)](https://github.com/jetify-com/devbox/actions/workflows/cli-release.yml?branch=main) +[![Built with Devbox](https://www.jetify.com/img/devbox/shield_galaxy.svg)](https://www.jetify.com/devbox/docs/contributor-quickstart/) ## What is it? -[Devbox](https://www.jetify.com/devbox/) is a command-line tool that lets you easily create isolated shells for development. You start by defining the list of packages required by your development environment, and devbox uses that definition to create an isolated environment just for your application. +[Devbox](https://www.jetify.com/devbox/) is a command-line tool that lets you +easily create isolated shells for development. You start by defining the list of +packages required by your development environment, and devbox uses that +definition to create an isolated environment just for your application. -In practice, Devbox works similar to a package manager like `yarn` – except the packages it manages are at the operating-system level (the sort of thing you would normally install with `brew` or `apt-get`). With Devbox, you can install over [400,000 package versions](https://www.nixhub.io) from the Nix Package Registry +In practice, Devbox works similar to a package manager like `yarn` – except the +packages it manages are at the operating-system level (the sort of thing you +would normally install with `brew` or `apt-get`). With Devbox, you can install +over [400,000 package versions](https://www.nixhub.io) from the Nix Package +Registry -Devbox was originally developed by [Jetify](https://www.jetify.com) and is internally powered by `nix`. +Devbox was originally developed by [Jetify](https://www.jetify.com) and is +internally powered by `nix`. ## Demo @@ -24,7 +36,9 @@ You can try out Devbox in your browser using the button below: [![Open In Devspace](https://www.jetify.com/img/devbox/open-in-devspace.svg)](https://auth.jetify.com/devspace/templates/tutorial) -The example below creates a development environment with `python 2.7` and `go 1.18`, even though those packages are not installed in the underlying machine: +The example below creates a development environment with `python 2.7` and +`go 1.18`, even though those packages are not installed in the underlying +machine: ![screen cast](https://user-images.githubusercontent.com/279789/186491771-6b910175-18ec-4c65-92b0-ed1a91bb15ed.svg) @@ -36,40 +50,56 @@ Use the following install script to get the latest version of Devbox: curl -fsSL https://get.jetify.com/devbox | bash ``` -Read more on the [Devbox docs](https://www.jetify.com/devbox/docs/installing_devbox/). +Read more on the +[Devbox docs](https://www.jetify.com/devbox/docs/installing_devbox/). ## Benefits ### A consistent shell for everyone on the team -Declare the list of tools needed by your project via a `devbox.json` file and run `devbox shell`. Everyone working on the project gets a shell environment with the exact same version of those tools. +Declare the list of tools needed by your project via a `devbox.json` file and +run `devbox shell`. Everyone working on the project gets a shell environment +with the exact same version of those tools. ### Try new tools without polluting your laptop -Development environments created by Devbox are isolated from everything else in your laptop. Is there a tool you want to try without making a mess? Add it to a Devbox shell, and remove it when you don't want it anymore – all while keeping your laptop pristine. +Development environments created by Devbox are isolated from everything else in +your laptop. Is there a tool you want to try without making a mess? Add it to a +Devbox shell, and remove it when you don't want it anymore – all while keeping +your laptop pristine. ### Don't sacrifice speed -Devbox can create isolated environments right on your laptop, without an extra-layer of virtualization slowing your file system or every command. When you're ready to ship, it'll turn it into an equivalent container – but not before. +Devbox can create isolated environments right on your laptop, without an +extra-layer of virtualization slowing your file system or every command. When +you're ready to ship, it'll turn it into an equivalent container – but not +before. -### Good-bye conflicting versions +### Goodbye conflicting versions -Are you working on multiple projects, all of which need different versions of the same binary? Instead of attempting to install conflicting versions of the same binary on your laptop, create an isolated environment for each project, and use whatever version you want for each. +Are you working on multiple projects, all of which need different versions of +the same binary? Instead of attempting to install conflicting versions of the +same binary on your laptop, create an isolated environment for each project, and +use whatever version you want for each. ### Take your environment with you Devbox's dev environments are _portable_. We make it possible to declare your -environment exactly once, and use that single definition in several different ways, including: +environment exactly once, and use that single definition in several different +ways, including: -+ A local shell created through `devbox shell` -+ A devcontainer you can use with VSCode -+ A Dockerfile so you can build a production image with the exact same tools you +- A local shell created through `devbox shell` +- A devcontainer you can use with VSCode +- A Dockerfile so you can build a production image with the exact same tools you used for development. -+ A remote development environment in the cloud that mirrors your local environment. +- A remote development environment in the cloud that mirrors your local + environment. ## Quickstart: Fast, Deterministic Shell -In this quickstart we’ll create a development shell with specific tools installed. These tools will only be available when using this Devbox shell, ensuring we don’t pollute your machine. +In this quickstart we’ll create a development shell with specific tools +installed. These tools will only be available when using this Devbox shell, +ensuring we don’t pollute your machine. 1. Open a terminal in a new empty folder. @@ -79,7 +109,8 @@ In this quickstart we’ll create a development shell with specific tools instal devbox init ``` - This creates a `devbox.json` file in the current directory. You should commit it to source control. + This creates a `devbox.json` file in the current directory. You should commit + it to source control. 3. Add command-line tools from Nix. For example, to add Python 3.10: @@ -89,13 +120,14 @@ In this quickstart we’ll create a development shell with specific tools instal Search for more packages on [Nixhub.io](https://www.nixhub.io) -4. Your `devbox.json` file keeps track of the packages you've added, it should now look like this: +4. Your `devbox.json` file keeps track of the packages you've added, it should + now look like this: ```json { - "packages": [ - "python@3.10" - ] + "packages": [ + "python@3.10" + ] } ``` @@ -105,7 +137,8 @@ In this quickstart we’ll create a development shell with specific tools instal devbox shell ``` - You can tell you’re in a Devbox shell (and not your regular terminal) because the shell prompt changed. + You can tell you’re in a Devbox shell (and not your regular terminal) because + the shell prompt changed. 6. Use your favorite tools. @@ -115,7 +148,8 @@ In this quickstart we’ll create a development shell with specific tools instal python --version ``` -7. Your regular tools are also available including environment variables and config settings. +7. Your regular tools are also available including environment variables and + config settings. ```bash git config --get user.name @@ -127,23 +161,30 @@ In this quickstart we’ll create a development shell with specific tools instal exit ``` -Read more on the [Devbox docs Quickstart](https://www.jetify.com/devbox/docs/quickstart/). +Read more on the +[Devbox docs Quickstart](https://www.jetify.com/devbox/docs/quickstart/). ## Additional commands `devbox help` - see all commands -See the [CLI Reference](https://www.jetify.com/devbox/docs/cli_reference/devbox/) for the full list of commands. +See the +[CLI Reference](https://www.jetify.com/devbox/docs/cli_reference/devbox/) for +the full list of commands. ## Join our Developer Community -+ Chat with us by joining the [Jetify Discord Server](https://discord.gg/jetify) – we have a #devbox channel dedicated to this project. -+ File bug reports and feature requests using [Github Issues](https://github.com/jetify-com/devbox/issues) -+ Follow us on [Jetify's Twitter](https://twitter.com/jetify_com) for product updates +- Chat with us by joining the [Jetify Discord Server](https://discord.gg/jetify) + – we have a #devbox channel dedicated to this project. +- File bug reports and feature requests using + [Github Issues](https://github.com/jetify-com/devbox/issues) +- Follow us on [Jetify's Twitter](https://twitter.com/jetify_com) for product + updates ## Contributing -Devbox is an opensource project so contributions are always welcome. Please read [our contributing guide](CONTRIBUTING.md) before submitting pull requests. +Devbox is an opensource project, so contributions are always welcome. Please read +[our contributing guide](CONTRIBUTING.md) before submitting pull requests. [Devbox development readme](devbox.md) @@ -153,9 +194,10 @@ Thanks to [Nix](https://nixos.org/) for providing isolated shells. ## Translation -+ [Chinese](./docs/translation/README-zh-CN.md) -+ [Korean](./docs/translation/README-ko-KR.md) +- [Chinese](./docs/translation/README-zh-CN.md) +- [Korean](./docs/translation/README-ko-KR.md) ## License -This project is proudly open-source under the [Apache 2.0 License](https://github.com/jetify-com/devbox/blob/main/LICENSE) +This project is proudly open-source under the +[Apache 2.0 License](https://github.com/jetify-com/devbox/blob/main/LICENSE) diff --git a/devbox.md b/devbox.md index eefc01d775d..3ba3485e6d2 100644 --- a/devbox.md +++ b/devbox.md @@ -1,27 +1,36 @@ + # devbox Instant, easy, and predictable development environments ## Getting Started -This project uses [devbox](https://github.com/jetify-com/devbox) to manage its development environment. + +This project uses [devbox](https://github.com/jetify-com/devbox) to manage its +development environment. Install devbox: + ```sh curl -fsSL https://get.jetify.com/devbox | bash ``` Start the devbox shell: -```sh + +```sh devbox shell ``` Run a script in the devbox environment: + ```sh devbox run