From 734a84502a18b7c2b56131afbda32c0772799bbf Mon Sep 17 00:00:00 2001 From: Andrew Novoselac Date: Wed, 10 Apr 2024 11:04:31 -0400 Subject: [PATCH] Improve readme --- CONTRIBUTING.md | 41 ++++++++++++++++++++++++++++++++++ README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0c863ae --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,41 @@ +# Contributing + +## Contributing to existing features + +We welcome contributions to the existing features in this repo. If you have found a bug, or believe additional tooling +should be included in the feature installation, you are welcome to create a Github issue or to open a pull request +yourself. For pull requests please use the following process: + +1. Fork this repository +2. Checkout a branch (on your fork) and commit your code +3. Push the branch to your fork on Github +4. Open a PR in this repository + +## Contributing new features + +The goal of this repository is to provide features for all common Rails dependencies. If you believe something is missing +that would be valueable to the Rails community, please open an issue in this repository. + +For specialized use cases, you can also create your own features. The devcontainer org's [feature starter repository](https://github.com/devcontainers/feature-starter) +is the best place to start. + +## Releasing features + +Features are released using the [devcontainers/action](https://github.com/devcontainers/action) Github Action. When +the `version` in a feature's `devcontainer-feature.json` is updated on the `main` branch, this action will publish a +new version of that feature to `ghcr.io/rails/devcontainer/features/[feature name]`. + +## Contributing to the ruby image + +The ruby image consists of a dev container that utilizes the ruby feature in addition to some common utilities. Thus +changes to how ruby is installed (eg installation of additional dependencies) should be made to the ruby feature. When +a new version of the feature is published, and new version of the image will also be published. + +For other changes to the image not related to the ruby installation, issues or pull requests can be opened following +the same process as for features. + +## Publish the image + +The image is published using the [devcontainers/ci](https://github.com/devcontainers/ci) Github Action. This workflow +is kicked off by the creation of a new tag on Github. Tags should be in the form `ruby-*.*.*`, where the * represent +the **image version** (not the ruby version). Images will be published for all `3.*.*` ruby versions. \ No newline at end of file diff --git a/README.md b/README.md index b05d376..6711a57 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,58 @@ -Docker images and devcontainer features for developing Rails and Rails apps. +# Rails Dev Container Images & Features +This repository contains dev container images and features that can be used to create a convenient and consistent +development environment for working on Rails applications. + +## What is a dev container? + +A **dev container** is a running Docker container that provides a fully-featured development environment which can be +used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in +continuous integration and testing. **Dev container features** are self-contained units of installation and configuration +that can be installed on top of a container image to provide additional functionality in a container. **Dev container +images** are prebuilt docker images based on dev container features. For more information on the dev container +specification see https://containers.dev/. + +## How to use the images and features in this repository + +As of Rails 7.2, all newly generated Rails applications will come with a dev container that utilizes the images and +features in this repository to create a development environment for that app. + +You can add a dev container to an existing application by creating `devcontainer.json` in the `.devcontainer/` directory +at the top level of the repository. A minimal dev container setup, for an application using SQLite and Active Storage +would look like this: + +```json +{ + "image": "ghcr.io/rails/devcontainer/images/ruby:3.3.0", + "features": { + "ghcr.io/rails/devcontainer/features/activestorage": {} + } +} +``` + +This dev container uses the Ruby image, which includes an installation of Ruby (in this case version 3.3.0) and the RBenv +version manager, as well as other common utilities such as Git. It also uses the Active Storage feature, which installs +dependencies needed for Active Storage. + +The dev container can be initialized [by VSCode](https://code.visualstudio.com/docs/devcontainers/containers) or by using +the [dev container CLI](https://code.visualstudio.com/docs/devcontainers/devcontainer-cli). + +Detailed information about the images and features provided by this repository can be found in their individual readme +files. + +## Contributing + +### Contributing to this repository + +This repository is open for contributions. See [the contributions guide](CONTRIBUTING.md) for details. + +### Creating your own features and images + +You can create your own features, and images based on them. + +The best place to start is the [feature starter repository](https://github.com/devcontainers/feature-starter) which is +maintained by the devcontainers org. + +## License + +The repository is released under the [MIT License](https://opensource.org/licenses/MIT). \ No newline at end of file