See the Marketing Site Information Architecture Refresh epic for single source of truth of pages being migrated to this repository.
Other keywords that may help folks find this section when searching the handbook:
In order to meet the goals of the information architecture refresh and serve the business, the Digital Experience team will need to move existing content, and in some cases, remove existing content.
We will do our best to find a solution that meets the business goals of the migration, and keeps your existing processes intact. We apologize in advance for any inconveniences incurred by this work. We will be doing our best to communicate with stakeholders in advance, but due to the scope of the migration, we may miss appropriate channels from time to time.
If we have moved or removed your content and it's causing problems for you, your team, customers, or other stakeholders, here are steps you can take to escalate these issues to us:
www-gitlab-com
repository.#digital-experience-team
Slack channel.All content is stored in the /content directory and can be accessed via the Nuxt content module
/solutions/
, /partners/
, /topics/
) the components will already be built for you. If it is a completely new page, please request support from the Digital Experience Team via this issue template..yml
file. Please follow existing indentation and convention.Reviewer
. Only the Digital Experience Team will be able to merge.Probably not. As we reduce the size and scope of the marketing site, we will be raising the bar for the quality of our page design. Content management systems present significant challenges in quality control.
In order to keep the Buyer Experience looking as good as possible, we have decided not to allow for markdown or rich text editing experiences. Instead, all data will continue to be rendered with the aforementioned Nuxt Content Module. Most data should live in YAML files as structured blocks of strings. There may be call for some numerical data from time to time. We will not allow or support markdown or other rich text strings, with the notable exception that some text elements may need inline links, which we can store as single p
tags with anchors in them, and render with Vue.js v-html
attributes.
By making this decision, we will be simplifying and streamlining our architecture, and making changes to the website more predictable and manageable. The cost is that some content editors may need to wait longer for engineers to implement their changes. Fortunately, in 2022, we only saw about 2-3 requests per month that required this kind of work across the Buyer Experience repository and www-gitlab-com repository.
If, in any particular quarter, we spend more than two weeks doing content updates implemented by engineering, we should revisit the need for a content management system.
The README.md at the repository root and our /docs directory.
See /docs/deployments.md.
The CHANGELOG.md is a file that contains the information of the changes made to the repository on every new version release. In our case, we are releasing a new version per iteration running a job at the end of it.
Every new release will create a tag in the repository's tag list and it is named using Semantic Versioning.
There are two main advantages of having this process in the project.
The first one is having versioning tags, sometimes it is necessary to make a rollback to a previous version due to a critical bug or an unexpected error. Each of these tags has a pipeline that can be run to deploy any version needed.
The second advantage is that having a Changelog
file, there is a single source of truth and a history of every MAJOR, MINOR and PATCH version,
making it easier to find any change without having to go back and search the project's board of past iterations.
In order to accomplish the changelog
automated updates, tag creation and version management, we are using semantic-release,
which is a package that helps automate the whole process and has great community of developers behind it. The specific configuration and technical details can be found in the docs.
A manual/scheduled pipeline job will be run at the end of each iteration cycle, in order for semantic-release
to detect correctly how to increase the release version, it needs Merge commits
to follow the guidelines from conventional commits.
Here is the list of types that can be used in the commit message:
Here are some commit message examples and how they affect the version increase:
Message | Version increase (v1.0.0) |
---|---|
fix(Homepage): Fix broken link |
v1.0.1 |
feat(Homepage): Add new section |
v1.1.0 |
feat(Services)!: Replace services module |
v2.0.0 |
style(Homepage): Change button colors |
No version increase |
After running the job, a new tag is created, the changelog file is updated and the package.json
version is increased.