Add a devcontainer configuration

[emisargent]

This change adds the .devcontainer directory with a devcontainer.json, post-create-command.sh, and welcome-message.txt. The devcontainer configuration automatically runs the initial setup commands when a user creates a codespace from their forked repository, making it easier for users to get setup and start contributing.

I opted to exclude virtual environment setup since a codespace is already an isolated, dedicated development environment, and users will only be able to access a single project (i.e., Flask) per codespace.

You can test these changes in a codespace by clicking the Code dropdown in this PR.

In VS Code, open the Command Palette from the settings gear icon and run the "Codespaces: View Creation Log" command to verify all dependencies were correctly installed.

• fixes Support using GitHub Codespaces by adding a devcontainer #4965

Checklist:

• Add tests that demonstrate the correct behavior of the change. Tests should fail without the change.
  Python tests aren't applicable to these changes
• Add or update relevant docs, in the docs folder and in code.
• Add an entry in CHANGES.rst summarizing the change and linking to the issue.
• Add .. versionchanged:: entries in any relevant code docs.
• Run pre-commit hooks and fix any issues.
• Run pytest and tox, no tests failed.

[emisargent]

@davidism Thanks in advance for the review! If you have any questions, I'll be happy to answer on Monday.

[emisargent]

Moving back to drafts while I make some other changes.

[davidism]

The virtualenv is not activated in the terminal that is opened when I create the dev container. As I was switched away typing this, it looks like another process kicked in and started post-create-command.sh. While it was running, the welcome message disappeared, then reappeared after it was finished, if I hadn't been watching I would not have known whether it had run or not, there was no "waiting to start" or "finished" indicator. After it completed, the virtualenv was still not active in the current terminal.

[davidism]

Out of curiosity, is the feedback from working on this going back to the Codespaces team as issues to improve the Python integration?

[davidism]

Is there a way to just not open a terminal or show a welcome message? Or to show a "wait, still setting up" modal, preventing interaction until the setup is complete?

[davidism]

How can I get a codespace without VSCode installing every extension I have locally as well? Most of those are useless for this devcontainer, and are slowing down the setup process.

[davidism]

It looks like Codespaces is not following the https://containers.dev spec, it does not honor "waitFor": "postCreateCommand" and instead presents the UI to the user immediately. It also has undocumented behavior such as first-run-notice.txt that forces an interactive terminal to open (why doesn't it just pop up a non-interactive log terminal like other tools?).

If I wait a really long time, eventually Codespaces decides to pause installing all my local extensions and runs post-create-command.sh (in the background, with no indication in the visible terminal). If I remove that environmentChangesRelaunch setting, and wait a really long time without touching anything (even though a new user would likely have started working by now since the IDE is responsive), eventually the terminal does activate the virtualenv.

I'm excited for Codespaces as a way to onboard contributors, but if this is the experience of just getting a basic Python environment working (Flask is really basic compared to most projects), I'm not confident I'm going to be able to maintain this, and I'm worried I'll get more user confusion.

Also, if I open this project locally in VSCode and choose "Dev Containers: Reopen in Container", I do not get the same behavior, everything just works. The project UI is hidden, a terminal opens showing the progress of postCreateCommand, and once the venv is actually set up that terminal closes and the project appears.

[emisargent]

Thanks for the feedback - I will be sharing this with the team. Part of my goal in initiating this PR is to identify friction points. Another part of my goal is for me to gain a better understanding of devcontainers in general, so I appreciate your patience in this respect.

How can I get a codespace without VSCode installing every extension I have locally as well?

This is a question I have as well, and will bring to my team.

The virtualenv is not activated in the terminal that is opened when I create the dev container.

As mentioned here, the venv will activate in any new terminal. This is why I added the venv activation step to the custom welcome text, and added the environmentChangesRelaunch setting to prevent the welcome text being cleared away. This may not be necessary with the change I implemented below.

I'm excited for Codespaces as a way to onboard contributors, but if this is the experience of just getting a basic Python environment working (Flask is really basic compared to most projects), I'm not confident I'm going to be able to maintain this, and I'm worried I'll get more user confusion.

Because this is a simple project with few dependencies, I removed the postCreateCommand and instead pushed installation tasks into the onCreateCommand. This means that loading the codespace will take more time up front (in the loading screen), but once users are in the container they can start working right away. This should help minimize confusion.

I hope that by putting in the effort to find the right configuration for Flask, we can more easily add codespaces support for the other Pallets projects!

[emisargent]

How can I get a codespace without VSCode installing every extension I have locally as well?

Quick followup - there is not currently a way to prevent specific extensions from being installed. However, this feature has been requested previously and is on the radar for the decontainers organization. See devcontainers/features#386 for additional info.

[emisargent]

I made a few more tweaks to clean this up. Since we don't currently have a workaround for the extension loading issue, I also reenabled the environmentChangesRelaunch setting to make sure contributors have the instructions to activate the venv in front of them at launch. The venv will still activate automatically in the existing terminal and any new terminals after the Python extension is fully installed.

Let me know if you have any further questions/suggestions, but I think this PR is ready to go! Thanks again for the great feedback.

[davidism]

Since the guide instructs contributors to fork first, is this necessary? When I open a codespace on this PR, I see your fork as origin, and pallets as upstream. Maybe we just change the guide, probably a bit simpler to push to origin than to remember to push to fork.

Additionally, is there any way to automate creating the fork so that users can start the codespace from pallets? I think the basic GitHub editor does this.

[emisargent]

Good catch - I've removed this section and added instructions for automatic forking. If starting from pallets, users will be prompted to create a fork the first time they make a commit. Reference docs are here.

[davidism]

Looking much better now, thanks. Let me know if there are specific issues I should subscribe to regarding the different things that have come up.

[davidism]

I'm about to merge this, I think it's in a good enough place for contributors at this point. I'm going to run a sprint at PyCon two weeks from now, so I'll get more feedback then. @emisargent have you reported any feedback so far to GitHub? Where can I follow discussions/issues? And where should I provide more feedback in the future?

Here's a summary of the issues I'd like to see improved:

• /usr/local/etc/vscode-dev-containers/first-run-notice.txt is not documented. It doesn't have any effect in generic dev containers, only on codespaces. It's not possible to disable the message completely.
• VS Code opens up and becomes usable before setup is finished. It should be possible to wait until the environment and IDE is completely set up before allowing the user to interact with it.
• It's not possible to disable installing all the extensions I have installed locally, which greatly slows down the IDE setup and exacerbates the "wait for virtualenv" issue.
• At PyCascades, @crazy4pi314 tried to create a custom Docker image instead, so that the virtualenv already existed as early as possible. However, it seems like again Codespaces is not behaving the same as devcontainers, or at least isn't documenting things enough. The big issue was that it wasn't possible to know/create the user that generic/codespace/jetbrains would use in the container, to have everything owned by the correct user. She probably has some more notes that I've forgotten.
• I tried pushing to this PR in a codespace, and both git push in the terminal and the panel UI prompted to create a fork instead. That's good for most users, except that I'm a maintainer so I should be able to push directly to your branch, but it's not recognizing that in the codespace.
• There's no documentation about how forks and remotes are set up with codespaces. It looks like an upstream remote is added for this PR, with your fork as the origin. But is that the case when a new contributor clicks on the codespaces button without creating a fork first? Does GitHub create the fork automatically like it does with the current simple editor?

[davidism]

I was going to enable prebuilds, since it sounded like that might speed up the virtualenv issue, but it looks like that's disabled for the pallets organization. Is it possible to get that enabled?

[crazy4pi314]

The prebuilds if run frequently can add up cost-wise quickly, so picking a low frequency trigger is helpful for budget constraints :)