Skip to content

Add staging rename design doc #2229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 5, 2025
Merged

Add staging rename design doc #2229

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ae2b28a
Add staging rename design doc
waxlamp Mar 21, 2025
b7fac4f
Delete stray word
waxlamp Mar 25, 2025
ce2bf06
Include link for new URL
waxlamp Mar 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions doc/design/staging-rename.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Rename "staging" to "sandbox"

We have long referred to our test deployment of the DANDI Archive as “staging”. This is due to our deployment workflow, which auto-deploys whatever is on `master` to https://gui-staging.dandiarchive.org, allowing us to test features in a production-like environment before they are deployed to actual production. We have additionally advertised this deployment to archive users as a way to try things out in a safe area before doing real work on the production instance.

The latter usage has led to user confusion about the role of the staging deployment. Specifically, the name “staging” makes people think that they are supposed to put data here for review and cleaning, etc., before it makes its way to a more permanent home somewhere.

To avoid that confusion, we are changing the name of the this deployment from “staging” to “sandbox”, better reflecting the end user experience of this deployment. Despite the name change, we will continue to use our deployment strategy without any changes.

## Requirements

The following changes will be required to make this name change happen.

1. **New URL for sandbox deployment.** The deployment formerly known as “staging” will be accessible at `https://sandbox.dandiarchive.org`.
2. **New URL for sandbox API.** The corresponding Django API app will be accessible at `https://api.sandbox.dandiarchive.org`.
3. **Redirections for old URLs.** To prevent user pain, we will redirect requests to the old application and API URLs to the new ones:
1. [`https://gui-staging.dandiarchive.org`](https://gui-staging.dandiarchive.org) → `https://sandbox.dandiarchive.org`
2. [`https://api-staging.dandiarchive.org`](https://api-staging.dandiarchive.org) → [`https://api.sandbox.dandiarchive.org`](https://api.sandbox.dandiarchive.org) (using HTTP 308 to preserve the request method)

The second redirection is probably less important for end users (excluding those that have written, e.g., Python scripts using the DANDI API against staging/sandbox for some reason), but it is necessary to avoid deprecating all previous versions of the DANDI CLI tool which still presumably references the old URLs.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@yarikoptic, @jwodder, could you confirm the claim about deprecating earlier versions of dandi-cli?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@waxlamp I'm unclear what you're asking. Of course old versions of dandi-cli point to api-staging. What else would they do?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I should have been clearer. I was assuming that you would not want to deprecate all previous versions of dandi-cli just to accommodate a change in the URLs, and that's what I was asking for confirmation on.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i would be ok with deprecating prior cli versions when this change happens.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My 1c would be -- to not bother. If someone runs into an issue, an obvious solution would be to upgrade. But as not everyone is using staging, and client would work perfectly fine with the main and other instances (and actually for downloads should work also with renamed one) -- we should be all good.

For the longer run eventually we should likely address

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(and actually for downloads should work also with renamed one)

It will not work for sandbox unless we redirect api-staging to api.sandbox, right? (That's what's at issue here, whether we need to put that redirection in place. But I think we should just do so.)

We will plan to run the redirections indefinitely, though, at any point in the future, we can retire them after announcing our intention to do so.
4. **Application code updates to use the new URLs.** Any references to the old URLs within Vue or Django application code must be updated to the new ones.
5. **Userbase notification.** We need to inform users about the URL change.
6. **Update documentation.** The documentation ecosystem must be updated to refer only to the new URLs and the new name of the deployment.
7. **Update ecosystem tooling.** We need to make sure the rest of the DANDI ecosystem (DANDI Hub, DANDI CLI, etc.) continues functioning normally.