Improve documentation of development process when using environments

[gabriel1]

Environments as a concept is quite well documented. What I’m missing is a recommended development workflow and I’ve been missing it since 2023

Let’s say you have turned on Force the use of sandbox environments to enforce that each schema change must be handled via a migration. Then the simplest development workflow that I can think of looks like this:

1. Make a fork of primary environment and a corresponding feature branch in git
2. Make schema changes in the sandbox environment and update code on the feature branch to work with new changes
3. While developing you must occasionally run migrations on the sandbox environment to make sure it is up to date with other changes that may have been applied to primary
4. Add content to the sandbox environment to verify that the feature works like it should
5. When feature is done, generate migrations to record the schema changes made from this branch

The deployment steps will be

1. Turn on maintenance mode in DatoCMS
2. Apply the migrations to primary to create a new sandbox environment
3. Copy paste the content from the old sandbox environment to the new sandbox environment
4. Test that everything works
5. Merge the feature branch in git
6. Promote the new environment to primary
7. Deploy the code changes to production
8. Turn off maintenance mode

This is not trivial! And there are also some risky bits such as

• If the site is not entirely static but make Dato-requests at runtime then there is a risk that the production site start to fail, between the promotion of the new primary and the deploy of the new code, if the schema changes were not backwards compatible.
• If the content is complex there is a lot of copy paste especially if there are multiple languages involved.

I feel that you have probably worked internally to optimize the above workflow for your own use case and I’m sure you there are best practices that you can share. Perhaps the migration can be run with a Github action as part of the deploy process? Perhaps there is another way to structure work that reduces the number of steps?

Regardless I think it would be nice for existing and new users alike if you could add dev process examples to the help page: Primary and sandbox environments — DatoCMS

[roger]

Hey @gabriel1,

While a good idea, this is one of those gray areas of a headless setup where there’s not necessarily one “correct” answer. There are endless frontend stacks and workflows, and what works for one team might not be the best answer for another team…

Even if you standardized on a single framework, say Next.js, the deployment strategies could vary between the Pages Router, the App Router, and whether you use React Server Components and/or clientside fetches.

The variability between hosts would likewise be quite complicated… having a hot-swappable “deploy to prod only on success” build system like Vercel is quite different from a static build on Cloudflare Pages, for example, or some homebrewed thing using OpenNext.

---

Just as an example, another env-based workflow could be a blue-green deployment strategy where the staging codebase is developed against the staging Dato env. New content is added to both the primary env and the staging one simultaneously (or maybe there’s a short content freeze and a record copy over). That way, the staging frontend is tested against upcoming real data instead of placeholders.

When the time comes, a frontend switch (either a rebuild or a DNS flip or otherwise “mark as prod”) happens, and instead of using a migration, the staging env in Dato is promoted to main. Then that env is itself forked again, to become the newest staging env.

I’m not saying this method is any better or worse than the one you outlined, just that there are different options and workflows. I think this is just one of those double-edged swords of headless development, where you have infinite freedom to alter your workflow, but because of that, our stack and docs are less opinionated and don’t just suggest a “one true way” of doing something.

---

That said… do you (or anyone else reading this thread) think there are one or two overwhelmingly popular deployment strategies common across teams & companies? Perhaps the one you suggested?

If there is a clear winner there in terms of a most popular methodology, then yes, perhaps we can better document that…?

I’ll also ask some of our devs for their input here, if they have any.

Thanks for bringing this up for discussion!