# IPFS legacy docs deprecation: process and checklist

This document represents the steps (or possible steps) that need to be undertaken in order to _remove_ the legacy docs.ipfs.io site and _migrate_ the beta docs-beta.ipfs.io site to the `docs.ipfs` subdomain.

All items have an indicator of the approximate time an item may take, but fine-tuned ordering of the items, as well as calendar scheduling, will be deferred until we know our target deprecation date. As such, it should be remembered that both _time required_ and _timeframe_ are approximate and subject to change.

## As soon as target deprecation date is known

- **Add deprecation alerts to legacy go-to-beta callouts**
_Effort needed: 1 day for design, 1 day for search/replace/deploy_
- Amend existing go-to-beta callouts on legacy site with date of deprecation and advice to update bookmarks and site links

- **Add "this URL will be changing" messaging to beta site pages**
_Effort needed: 1 day for design, 1 day for deploy_
- Add tip-style callout to beta site letting users know URL is changing, and to update bookmarks accordingly

## Bulk of pre-deprecation work (to prioritize in order of scope/effort required)

- **Prepare the necessary redirects and create a master redirect list**
_Effort needed: 1 week_
- Document the needed redirects from legacy site to their final destinations post-deprecation (URL on legacy docs.ipfs.io -> another URL on "new" docs.ipfs.io)
- Document the needed redirects from beta site to the final URLs post-deprecation (docs-beta.ipfs.io/foo/bar -> docs.ipfs.io/foo/bar)
- Double-check throughout for duplication or collision
- Note that the legwork of finding equivalent URLs has already been done in each site's callout boxes cross-linking between legacy and beta
- Investigate how we're actually going to implement the redirects; who in infra needs to help?
- > its mostly about http:// (link rot on regular web), so I believe we should handle this at Nginx level. Old paths should return HTTP 302 to the new content, then if we confirm everything works as expected, change them to HTTP 301. [name=lidel]

- **Check for old legacy site redirects and act accordingly**
_Effort needed: 1 day, more if help needed from infra_
- Are there any old, existing redirects on the legacy site that will be overwritten by our other redirect work? If so, remedy

- **Prepare new sitemaps for Google Search Console/Bing Webmaster Tools**
_Effort needed: 2 days, including research_

- **Examine top inbound-links referrers for proactive-fix opportunities**
_Effort needed: 2 weeks ... this can get tedious_
- Examine top referrers for inbound links to see if there are any opportunities to directly contact those referrers and ask links to be changed
- Contact, track, follow up
- Find GitHub repos and add pull-requests to change and relevant links.

- **Deploy custom 404 page**
_Effort needed: 1 day, unless deployment hitches_
- Create custom 404 page with "did you mean ..." links to top site content as determined by GA, plus opportunity to give feedback or open an issue
- **Open question:** Is this actually possible given our IPFS hosting situation?
- > its possible to customize 404 at Nginx level, but this customization won't work if website is loaded from a custom gateway. Open issues for solving this at go-ipfs level: https://github.com/ipfs/go-ipfs/issues/5916, https://github.com/ipfs/go-ipfs/issues/6214#issuecomment-558704348 [name=lidel]

- **Design for how to remove "this site is in beta" content from page footers**
_Effort needed: 1 day for design, 1 day for deploy_
- We're removing the "this site is in beta" content from page footers, but the links to improving content and filing issues need to remain; design for this

- **Determine what needs to be done regarding separating/joining metrics in Google Analytics/Google Webmaster Tools**
_Effort needed: 1 week_
- Consideration: We don't want to lose our old analytics figures, because we want to use them for comparison
- Consideration: The beta site will eventually live at the same subdomain as the legacy site (docs.ipfs.io)

## Last steps (e.g. one week) before deprecation

- **Increase urgency of deprecation alerts on legacy content**
_Effort needed: 1 day for design, 1 day for search/replace/deploy_
- Rely on visual cues: make background color red, replace laptop image with alert triangle, etc

- **Search `ipfs/ipfs-docs-v2` repo for "beta" and act accordingly**
_Effort needed: 1 day_
- This is mainly a sanity check and to make sure we didn't unintentionally refer to the beta in docs running test

- **Search all relevant repos for "noindex", "nofollow", etc, and act accordingly**
_Effort needed: 1 day_
- Mainly a sanity check to make sure we aren't accidentally cutting ourselves off from search indexing somewhere

## On target deprecation date

- **Implement the redirects**
_Effort needed: 1 day_
- Work with infra (or whomever) to make sure the redirects are implemented - preferably in one go - in time to account for any DNS propagation or similar
> Initially use HTTP 302, just to be safe [name=lidel]

- **Change robots.txt so sites are indexed**
_Effort needed: 1 day_

- **Change beta-site callouts to "this URL has changed"**
_Effort needed: 1 day for search/replace/deploy_
- Change the callout on beta pages to "this URL has changed, update your bookmarks"

- **Remove "this site is in beta" content from page footers**
_Effort needed: 1 day for search/replace/deploy_

- **Remove "beta" icon from site header**
_Effort needed: 1 day for deployment_

- **Submit new sitemaps to Google Search Console/Bing Webmaster Tools**
_Effort needed: 1 day_

## Soon after deprecation date (e.g. within a week)

- **File with Google's [Change of Address](https://support.google.com/webmasters/answer/9370220?hl=en&visit_id=637115245592733123-1252940477&rd=1) tool**
_Effort needed: 1 day_

- **Make any changes to Google Analytics/Webmaster Tools accounts**
_Effort needed: 2 days_
- If any decisions above regarding GA/Webmaster Tools accounts need post-deprecation resolution, do so now

- **Rename `ipfs/docs` to `ipfs/docs-legacy` and archive it; POTENTIALLY rename `ipfs/ipfs-docs-v2` to `ipfs/docs`**
_Effort needed: 2 days_
- Add labeling structure to `ipfs/ipfs-docs-v2` so ZenHub tracking still works
- Transfer all open issues in `ipfs/docs` to `ipfs/ipfs-docs-v2`; make sure labels transfered (try a test issue first), and re-label accordingly if not
- Search VuePress .md files (and any other VuePress site variables) for any direct links to `ipfs/docs` issues (probably only in content stub pages) and update these accordingly
- Rename `ipfs/docs` to `ipfs/docs-legacy`
- **Potentially** rename `ipfs/ipfs-docs-v2` to `ipfs/docs`, but note that doing so will break redirects to `ipfs/docs-legacy` in the event that someone direct-links to legacy content (see [discussion](https://github.com/ipfs/docs/issues/309#issuecomment-564669129)) — one alternative may just be to rename `ipfs/ipfs-docs-v2` to something that sounds less transient, like `ipfs/documentation`
> `ipfs/docs-website` is pretty self-explanatory and follows preexisting convention: [ipfs/ipfs-cluster-website](https://github.com/ipfs/ipfs-cluster-website/), [multiformats/cid-utils-website](https://github.com/multiformats/cid-utils-website) [name=lidel]
- Update `ipfs/docs-legacy` readme and repo description to make it clear where folks should go instead
- Archive the `ipfs/docs-legacy` repository (see [this GitHub blog post](https://github.blog/2017-11-08-archiving-repositories/) for details)
- Clean up anything that this may break in terms of live-site rendering, particularly searching live repo for `ipfs-docs-v2` to ensure we aren't hard-linking to anything that will vanish

- **Fix links in all PL's repos**
_Effort needed: 2 days, since likely will involve a bunch of PR approvals_
- Search all PL repos for "docs.ipfs" and change the links accordingly using data from the master redirect list
- Include ProtoSchool - see [issue #339](https://github.com/ProtoSchool/protoschool.github.io/issues/339)

## Post-deprecation followup (approx 6-12 weeks)

- **Remove "this URL has changed"** callouts
_Effort needed: 1 day for search/replace/deploy_
- Should be reasonably soon after deprecation to avoid banner blindness; two weeks?

- **Recrawl all old and new URLs to check that they are working properly**
_Effort needed: 1 day_
- Recrawl all (legacy) URLs previously on docs.ipfs.io to confirm they redirect correctly
- Recrawl all URLs on docs-beta.ipfs.io to confirm they redirect correctly
- Visit all URLs on new site to confirm nothing 404s
- Fix any issues that arise

- **Examine top 404 referrers for contact opportunities**
_Effort needed: 1 week ... this can get tedious_
- Examine top traffic referrers on error pages; if there's anyone we can contact directly to resolve, do so