The navigation repository (also known as
be-navigation) is a separate package that is updated and maintained independently from the rest of the marketing website. This is so that we can make changes in one place, and have any consuming repositories pull from that single source of truth. The navigation is currently maintained by the Digital Experience team.
To request changes to the Navigation repository, please fill out an issue here to be triaged by the Digital Experience team.
If you would like to self-serve changes to the navigation, feel free to clone the project locally following the instructions in the readme. Once you make changes, please tag a member of the Digital Experience team to review your MR. We are consistently running tests on navigation links, and doing research and design spikes on navigation changes, so all changes will need to be approved by a member of our team.
When making a change to the navigation, it's important to check for an AB test. The quickest check is to look at the file system for the navigation repository. Is there a folder for
Navigation as well as a folder for
NavigationB (or some other duplicate name that contains similar files)? If so, be sure to make your changes in both folders, so that both variants will see the updates.
Currently, our team releases new navigation changes in bundles on Wednesdays. This can be adjusted as necessary, and we typically opt to release large, breaking changes in their own version.
We avoid deploying minor or major releases of the navigation on release post days.
Navigation release: Version x.x.xxand include links to the MRs and Issues included in this release. This navigation issue should be added to the quarterly navigation release epic (ex. FY23Q3 epic)
main, with all changes
npm run build-library(optionally use
yarn linkfor a detailed local review)
npm publish(Note: You may need to login with your npm credentials using
To update the navigation in the repositorys that consume it, for example www-gitlab-com, or buyer-experience:
package.json, find the
be-navigationline item, and increment to the latest version
npm installto update the package
Cookie Preferences, and
Edit in Web IDEto make sure they work as expected
You can use the MR template in the buyer experience repo titled "navigation change". It contains the following checks, for a thorough runthrough of the navigation:
Note: You will have to visit pages built by that repository in order to see your navigation changes. For example, the website homepage is built in
Buyer Experience, so you can visit the homepage in your review app to see your navigation changes. However the handbook is built by
www-gitlab-com, so you'll need to go to a handbook page in order to test your navigation changes in the
www review app.
If you want to review locally changes made to the navigation:
yarn run build-library.
yarn link be-navigation.
yarn && yarn dev
Changes made to the navigation should be available in the BE or Dub repo for testing extensively on your local environment.
When we release larger versions of the navigation (beyond simply adding a link), we recommend using the semantic versioning alpha directive
For example, if you are looking to release verion
1.1.0 of the navigation, consider releasing version
1.1.0-alpha instead. You can then bring the alpha version into the consuming repositories, such as Buyer Experience, and test it out.
If there are problems, you can make changes in the navigation repo, release those changes as
1.1.0-alpha.1, test them, and so on, continuing to release "unstable" alpha versions until you're happy with the release.
Once the bugs are fixed, re-release the same code to npm as version
1.1.0, and merge everything in.
Although this means re-releasing identical code as a new version to npm, it saves us from incrementing multiple minor versions in one release.
We use LaunchDarkly as our AB testing tool. Because of the way the navigation is bundled and pulled into other repositories, we can't target specific items in the Navigation repo for testing. If we want to test something in the Navigation, we need to create a duplicate of the entire navigation component, make the changes in that duplicate version, and release two entirely complete navigations. If we're running an ABC test, we need to duplicate the navigation a third time.
This adds a layer of complexity, since we need to keep two or more distinct navigations up-to-date with any changes. It also takes a fairly lightweight package and doubles it in size. Due to this, when we run navigation tests, they should be testing genuine, burning questions the team has - we should run test for which we really need the data to drive a decision (i.e. Could this change be a "just do"?)
Once the two navigation components have been released, they can be used in the Buyer Experience repository like so:
<LaunchDarkly feature-flag="some-ab-test-id"> <template #control> <SlpNavigation /> </template> <template #experiment> <SlpNavigationB /> </template> </LaunchDarkly>
You may need to add click events on elements in the navigation, depending on the data you're looking for. Questions about this can be directed to the #digital-experience-team slack channel. We are not set up to run tests in the
www-gitlab-com repository at this time.