devcontainers-contrib/.github

Community Dev Containers Charter

The Community Dev Containers project aims to document, maintain, and improve on the official devcontainers images, features, and templates to improve the developer experience for end-users.

Guiding Principles

The Community Dev Containers project operates under principles similar to those of the OpenJS Foundation. It operates collaboratively, openly, ethically, and transparently. Project proposals, ideas, timelines, and statuses should not merely be open and available, but also easily visible to outsiders. Outside users and developers should be able to participate in discussions, ideas, issues, and make contributions with as little effort as possible.

Problem

The current official @devcontainers project's scope is limited to features, images, and templates that serve only the highest level of most popular programming environments.

For instance, the devcontainers/features repository contains only 28 different addons. The devcontainers/images repository only has a selection of 15 different development environment baselines.

This project is the centralized unofficial hub for other features, images, and templates that would not be permitted to fall under the official @devcontainers umbrella.

Scope

The @devcontainers-contrib organization maintains and evolves the images, features, templates, and documentation content for aspects not covered by the official @devcontainers organization. It provides a stable, yet flexible, set of supporting software for users who use dev containers that is governed to accomodate their desires. This project's value is its balance between administration and community adherence. It's scope includes listening and responding to user feedback.

In-scope

• Docker images for ecosystems not covered an official dev containers image
• Feature collections for popular tools that are typical on developer computers
• Templates for popular project configurations and setups
• Conventions and best-practices to follow architecting a dev container
• Make it easy to propose, add, or otherwise discuss additional features, images, and templates

Tutorials and guides on how to use dev containers are not covered under the umbrella of the Community Dev Containers project. These items can be pursued by individual members, but are not endorsed or covered under this organization's scope.

Out-of-Scope

• Creating a dev container feature for every single Node.js or Python package
• Maintaining a dev container image for all permutations of tooling mashups
• Fixing users' broken dev container configurations
• Answering questions about decisions made by the official @devcontainers organization

.github's Issues

Enable organization discussions

@danielbraun89 Please please pretty please enable organization discussions. 🙏 I would very much appreciate it if my brain were soothed by using Discussions for discussions instead of Issues.

I recommend that they be tied to this .github meta repo.

1. Enable discussions on this .github repo
2. Enable organization discussions
3. Tie them to this repo

More resources:

• https://docs.github.com/en/discussions/quickstart#enabling-github-discussions-on-your-repository
• https://github.blog/changelog/2022-04-12-organization-discussions/

[discussion:general] What should be a template, image, feature, postCreateCommand?

This should be an org-wide discussion. Once Discussions are enabled on this org/repo, move this issue to a Discussion pls @danielbraun89.

I am creating this Discussion to centralize discussion on this particular topic. This topic of "what makes a feature a feature?" and "what belongs in a feature and what goes in a postCreateCommand?" has been discussed in https://github.com/devcontainers-contrib/features/discussions/171, https://github.com/devcontainers-contrib/features/discussions/173, and now https://github.com/devcontainers-contrib/features/discussions/202. This is a centralization of those questions.

To elaborate on the question, we want to address this particular example scenario: (If you have another wrench to throw on the pile, feel free to do so; this is a contrived example that attempts to cover most edge cases)

A user is writing a Python project that uses Prettier to format the README.md file. They use Poetry to manage dependencies for this Python project. Their API documentation is generated using Sphinx. They use GitHub Actions to build, test, and publish the project. They also want to use poethepoet for task running.

Open questions (these are the ones that warrant discussion)

1. Which devcontainer template should they use to create their initial devcontainer.json file?
2. Which devcontainer image should they use as a base?
3. What features should they use and what options should they pass to them?
4. What should go in the postCreateCommand?

My own (@jcbhmr's) opinion on this is posted as a comment to this Discussion.

[discussion:idea] Add workflow template for deploying to GitHub wiki

I just discovered that you can make GitHub Actions workflow templates for users or for organizations! 😲

I think it'd be a good idea to add a workflow template for deploying to a GitHub wiki to this organization since I'm guessing that such a workflow will be reused many times (if/when another repo gets the wiki/ treatment like devcontainers-contrib/features did).

📚 Creating starter workflows for your organization

Rename & add description

We also should probably change the title & add a description.

Sidenote: Should it be "Devcontainers" capitalized when starting a sentence? Or should always be "devcontainers"? Thoughts?

I suggest one of:

devcontainers community

Unofficial community-run bazaar for extra devcontainer docs, templates, and features

---

Community devcontainers

Unofficial community-run bazaar for extra devcontainer docs, templates, and features

@jcbhmr initiative

I know it's somewhat arrogant to call this the "@jcbhmr initiative", but I couldn't think of a more generalized name to describe the vastness of the stuff that this issue entails.

Proposition

Right now this repository appears to have a single "anchor" repository: the features repository. This is good, but I think this organization can be much more than just a features collection. I propose that we...

1. Expand to cover images, features, and templates
2. Add some target issues for what features/images/templates we want
3. Create web interfaces for browsing features/images/templates instead of README.mds in GitHub
4. Add more metadata and scope-defining goals and goalposts to this metadata repo
5. Enable organization discussions

Here's a draft charter/objective document that I wrote down: jcbhmr/devcontainers-contrib#jcbhmr-initiative

Why we should expand the scope of this organization beyond just features

1. I thought that's what the name "devcontainers-contrib" entailed: more stuff beyond the boundaries set by the official devcontainers org
2. I believe this org could become the "community hub" for devcontainers if played right
3. I want more images besides those that devcontainers/images offers, and this seems like the best spot

Tasks

• Create a .github repository
• Create a features repository
• Create a docs website for those features
• Create a images repository
• Create a docs website for those images
• Create a templates repository
• Create a docs website for those templates
• Enable organization discussions and tie them to this .github repo
• Create a README.md in this .github repo to outline the charter/objective
• Add links for all the things to the .github/profile/README.md organization page
• Document code conventions and other stylistic decisions in the .github wiki (for devs)

Ideas

These are things that I thought about and dismissed, but wanted to record and share.

• Create a devcontainers-contrib.github.io to host a landing page
• Rename this organization to something shorter than 21 characters (high friction, I know)

  Ideas:

  • ✅ devcontainersx
  • ✅ xdevcontainers
  • ✅ devtainers
  • ❌ devenv
  • ✅ envtainers
  • ✅ devenvcontainers
  • ✅ devpreset
  • ✅ codevenv

[discussion:idea] Create an awesome repo

I have come across numerous resources after becoming more active in this org and using devcontainers as a whole. I think creation of a devcontainers-contrib/awesome-devcontainers or devcontainers-contrib/awesome would be a good idea.

Here's some prior art:

• https://github.com/manekinekko/awesome-devcontainers Updated 4 months ago (Aug 29 2022)
• https://github.com/stereobooster/awesome-vscode-dev-containers Updated 2 years ago (Feb 10 2021)

Here's some examples of things that I'd like to put in an awesome list:

• Article: Getting Started with Dev Containers
• Article: Reproducable Development with Devcontainers
• Article: Adopting Remote Development Environments at Slack
• Project: some cool project with a good devcontainer.json
• Video: https://docs.microsoft.com/shows/beginners-series-to-dev-containers/
• ...

Alternatives

Instead of doing this, we could...

1. Embrace the existing manekinekko/awesome-devcontainers repo which seems to be the most up-to-date one
2. Leave such an awesome list to an individual user instead of under the @devcontainers-contrib umbrella

Why this idea is good

(Even if someone else maintains it)

1. Awesome lists are a great way to provide links to articles, resources, etc.
2. They index the ecosystem¹
3. They make it easy(-er) for beginners to get started with curated resources

Related idea: Could we create an awesome-codespaces index too? Should we? There doesn't seem to be anything on Google for that https://www.google.com/search?q=awesome+codespaces

Footnotes

1. For instance, if you want to know "What are all the Python web frameworks?" where do you go? To an awesome list! ↩

[discussion:general] What should go in postCreateCommand, postStartCommand, and postAttachCommand?

This should be a discussion. Once discussions are enabled, @danielbraun89 could you move this to the org-level discussions? #3

Originally from https://github.com/devcontainers-contrib/features/discussions/202#discussioncomment-4439676

TL;DR: I'm (@jcbhmr) no longer sure that poetry install should even be in the postCreateCommand spot. Maybe it belongs in something a little closer to the user like postStartCommand and maybe even postAttachCommand so that it's run multiple times.

devcontainers have multiple different lifecycle scripts. Here's a summary:

1. initializeCommand: A command string or list of command arguments to run on the host machine before the container is created.
2. onCreateCommand: finalizes container setup when a dev container is created. It and subsequent commands execute inside the container immediately after it has started for the first time. not typically have access to user-scoped assets or secrets
3. updateContentCommand: executes inside the container. execute at least once, but cloud services will also periodically execute the command to refresh cached or prebuilt containers. no user files or secrets.
4. postCreateCommand: once the dev container has been assigned to a user for the first time. can use this command to take advantage of user specific secrets and permissions. has local file access.
5. postStartCommand: run each time the container is successfully started. potentially multiple times per devcontainer over the course of days.
6. postAttachCommand: A command to run each time a tool has successfully attached to the container.

Open questions:

1. What should go in postCreateCommand? Just ./configure? ./configure && poetry install?
2. What (if anything) should go in postStartCommand? npm install? A dev preview HTTP server? A test watcher? Nothing?
3. Should anything go in postAttachCommand? Maybe a dev HTTP server? Test watcher?

My (@jcbhmr's) opinion is posted as a comment. Looking for more opinions!

/cc @imaxerik since I originally posted this on your thread then moved it here