Merge pull request #20 from rails/improve-readme

Improve readme & contributing guide

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.

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).