Create separate Middleman instance for the Handbook (Part 1: engineering and marketing dirs)
Who
The Static Site Editor Group and Brand and Digital Design team are working together to create monorepo structure for www-gitlab-com.
What
We are creating a distinct Middleman build for just the handbook. By isolating the handbook into a separate middleman build, we can start to develop handbook centric features for just this part of the site.
This issue will only involve moving the handbook/engineering
and handbook/marketing
directories, to reduce scope, and also because these map cleanly to the current "Part 5" of PartialBuild
. A follow-on issue (#7912 (closed)) will move the rest of the directories under handbook
.
NOTE: The "Related merge requests" section contains many cleanup/refactoring merge requests which were not directly related to this issue, but were identified and quickly fixed as part of this effort. See !49086 (closed) for more details and context on these.
Why
We are doing this so the handbook becomes isolated from other parts of the website and deployment times are reduced. This is also a required step toward creating a true monorepo structure for www-gitlab-com
Tasks
-
Move engineering
andmarketing
pages to separate build, but only symlinked at first. E.g. all the files inPartialBuild 5/9
, plus the handbookindex.html
. (!51499 (merged)) -
Give people notice that the files will be moving -
After the notice period, replace the symlinks in the above task with actually moving the files. (MR TBD) -
Ensure CODEOWNERS
was properly updated. -
Ensure that edit
andWeb IDE
links work at bottom of pages and via highlight tooltip for moved pages.- MR for link checker: !52129 (merged)
- MR to fix links: !52248 (merged)
-
Introduce a /data/monorepo_site_paths.yml
"single source of truth" for mapping sub-site source dirs/files to rendered paths.- Use it wherever mapping is needed. E.g.: in middleman config, edit/web IDE links, linter for edit/web IDE links, potentially other future places like CI config.
- This reduces risk of future errors, especially for future sub-sites that don't have as clean a mapping like
handbook
orblog
.
-
-
Review master pipeline and deploy to ensure everything is expected: https://gitlab.com/gitlab-com/www-gitlab-com/-/pipelines/153671688 - Spot checked one deployed file against previously deployed version, the only change was the expected edit links path change.
Notice Text
Hello! As part of the migration to a monorepo approach for `www-gitlab-com`, we will be moving the `source/handbook/engineering` and `source/handbook/marketing` folders under `sites/handbook/source/handbook. This will happen on this WEEKDAY, MONTH DATE after 15:00 UTC.
If you have open MRs or branches which have modified files in these directory, please finish and merge them before then, or be prepared to resolve conflicts before you can merge. If you need help resolving conflicts, or have other questions, please ask on Slack in #mr-buddies or in #handbook. More details in the issue and MR below. Thanks!
https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/6689
https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/51499
Replacing symlinks with actually moving files
git rm -rf sites/handbook/source/*
mkdir -p sites/handbook/source/handbook
git mv source/handbook/index.html.md sites/handbook/source/handbook/
git mv source/handbook/engineering sites/handbook/source/handbook/
git mv source/handbook/marketing sites/handbook/source/handbook/