This repository implements the new VTEX Help Center, improving merchants' experience as they consult our new feature announcements, tutorial articles, troubleshooting guides, and other documentation.
As the Help Center provides VTEX documentation to users, some of its main features are:
-
Multilingual content
All information present in the Help Center Portal is displayed in three languages (English, Portuguese and Spanish), allowing easy access to the content available on the platform.
-
Markdown files rendering
Markdown is a very popular markup language that helps making plaintext documents more semantic by adding formatting elements defined in its syntax. All documentation available on Help Center is written in markdown language.
The versioning process of this repository was built to automate version releases and standardize its contributions. The following goals are currently implemented:
-
Standardize the repository history by adopting a commit messaging convention that makes commits more semantic
Commitlint is a tool that lints commit messages according to Conventional Commits. Conventional Commits, on the other hand, is based on the SemVer (Semantic-Versioning) standard.
-
Automate
CHANGELOG.mdandpackage.jsonversion updates based on semantic commit messages, as well as the creation of new version tagsStandard Version provides a release script that results in a release commit containing a new version in
package.jsonand updates inCHANGELOG.md, all based on the changes introduced by the latest semantic commits. It also creates a new version tag. -
Automate new version releases when Pull Requests (PR) are merged into the
mainbranchA GitHub action named Release Version Workflow is triggered whenever a PR is merged into the
mainbranch. The action workflow contains steps that identify whether the PR should release a new version (and what type) to run the release script, submit its results, and generate a new GitHub Release corresponding to the new version's tag. The type of the new version may be automatically deducted from the semantic commits or determined by the user as a PATCH, MINOR or MAJOR.
flowchart TB
startState(PR is merged into main) --> setReleaseEnvVar(1. Extract release type from PR labels)
setReleaseEnvVar(Extract release type from PR labels) --If PR has 'release-auto', 'release-patch', 'release-minor' or 'release-major' label--> releaseVersionScript(Run release script)
setReleaseEnvVar(Extract release type from PR labels) --If PR has no release label--> setDefaultAutoRelease(Set default auto release)
setDefaultAutoRelease(Set default auto release) --> releaseVersionScript(Run release script)
setReleaseEnvVar(Extract release type from PR labels) --If PR has 'release-no' label--> endState(Finish workflow)
releaseVersionScript(Run release script) --> |Commit changes to CHANGELOG.md and package.json with the new version and create a new version tag| pushReleaseVersionScriptResult(Push script results to the remote repository)
pushReleaseVersionScriptResult(Push script results to the remote repository) --> createRelease(Create new GitHub Release)
createRelease(Create new GitHub Release) --> endState(Finish workflow)
- Clone this repo, access the command line at its root directory and install all dependencies:
yarn install- To start the application development server, run:
yarn dev- Open http://localhost:3000 with your browser to see the result.
Help Center is a Next.js app based on React and Typescript.
The diagram below represents the base structure defined to organize the files and folders of the repository, where all file names must follow the kebab-case convention.
flowchart TB
helpcenter --> src & public
src --> messages & components & pages & styles & utils & tests
messages --> ptJson{{pt.json}} & enJson{{en.json}} & esJson{{es.json}}
components --> some-component --> stylesCompCss{{styles.component.css}} & compOther{{functions/other.ts}} & compIndex{{indext.tsx}} & compStyle{{styles.ts}}
pages --> search & pagesLanding{{landing-page}} & announcements & docs & faq & known-issues & troubleshooting
search --> searchSearchPage{{search-page}}
announcements --> announcementsIndex{{index}}
faq --> faqsIndex{{index}}
know-issues --> knowissuesIndex{{index}}
troubleshooting --> troubleshootingIndex{{index}}
docs --> tracks & tutorial
tracks --> tracksIndex{{index}}
tutorial --> tutorialIndex{{index}}
styles --> stylesGlobal{{global.css}}
tests --> testsChildren{{tests files}}
utils --> utilsChildren{{Global functions, types and constants}}
- It is preferable to use arrow functions
- It is preferable to use functional components instead of class components
- It is preferable to use Hooks over Higher Order Components (HOCs)
-
ESLint is used to lint code and identify errors based on a pre-defined ruleset (
.eslintrc.jsonfile)Before any change is committed, a pre-commit hook will run the ESLint on JavaScript and TypeScript files located at pre-defined paths (such as
src/pages,src/componentsetc) to fix their errors (ignored paths are described in.eslintignore). -
Prettier is used to standardize the code formatting based on a pre-defined ruleset (
.prettierrcfile)Before any change is committed, a pre-commit hook will run Prettier and correct errors found in the appropriate files (ignored paths are included in
.prettierignore).
You might want to configure ESLint and Prettier in your code editor to see errors and correction suggestions at development time.
Within the repository we can consider three types of commit:
-
commits: Default commits performed by the user on GitHub.
-
merge commits: Commits through the command
git merge <branch> --no-ff(it is also generated when merging a Pull Request without squashing). -
release commits: Commits made using Standard Version tool.
Standard Version is a tool that simplifies the versioning process of a project. It has a release script that generates a new version tag and creates a release commit containing: a new version in
package.jsonand updates inCHANGELOG.mdbased on changes introduced by the latest commits.
-
Step 1. Stage the desired changes:
git add <filenames>
-
Step 2. Commit your staged files:
-
Option 1: Use the Commitizen script to make your commit with an interactive step-by-step via command line that helps generating semantic descriptions that follow the Conventional Commits model. Instead of runing
git commit, run the command below and follow the instructions that will appear:yarn cz-commit
-
Option 2: Make your commit manually following the Conventional Commits model:
<type>[optional scope]: <description> [optional body] [optional footer(s)]If there are any breaking changes introduced by your changes, follow one of the options:
- Append a
!after<type>[optional scope]<type>[optional scope]!: <description> [optional body] [optional footer(s)] - Add
BREAKING CHANGE: < breaking change description>to the footer<type>[optional scope]: <description> [optional body] BREAKING CHANGE: <breaking change description>
The
<scope>may specify the context of the applied changes (e.g. subject, component or file name), as well as the<body>may help explaning the commit in more details. The<type>helps making commit messages more semantic and all options are described in the table below.Commit <type>OptionsDescription Release* fixfixes bugs in your codebase PATCH featintroduces a new feature to the codebase MINOR docsdocumentation only changes PATCH stylechanges that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) PATCH refactora code change that neither fixes a bug nor adds a feature PATCH perfa code change that improves performance PATCH testadds missing tests or corrects existing tests PATCH buildchanges that affect the build system or external dependencies (scope examples: gulp, broccoli, npm) PATCH cichanges to CI configuration files and scripts (scope examples: Travis, Circle, BrowserStack, SauceLabs) PATCH choreother changes that don't modify src or test files PATCH revertchanges that revert previous commits PATCH * SemVer specification says the MAJOR version zero (0.y.z) is for initial development. Because of this, until this repository reaches a first stable version of Help Center (with a specified major release), the automatic release won't lead to any MAJOR version, but only PATCH and MINOR (breaking changes commits will result in MINOR bumps).
Examples:
# Commit message without scope, body, footer or breaking change chore: add favicon # Commit message with scope ci(versioning): add Release-Version GitHub workflow # Commit message with scope and breaking change feat(api)!: send an email to user when a request is submitted # Commit message with breaking change (footer) chore: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6.
- Append a
What NOT to do:
- Add dot in the end of text. E.g.:
chore: add favicon. - Start with uppercase. E.g.:
feat(api): Send an email to user when a request is submitted - Write in Portuguese. E.g.:
chore: Atualizar a navigation sidebar
-
Currently, we have one fixed branch: main.
The main branch must reflect exactly what is deployed in production, it should be treated as the single source of truth. It is from main where every development branch is created.
Important note: Only merge commits should be made by developers on
mainbranch.
You must create a branch based on main to start a feature, improvement, or fix. This branch is called a feature branch. It must have the following structure name: <type>/<description>
Choose the type that best summarizes your contribution at the Commit Types Table.
The feature branch description must be short and written with kebab-case. It should give a basic understanding of what is being developed on the branch.
E.g.: git checkout -b feature/landing-page.
Important note: Only commits should be made in a feature branch. None release or merge commits should be made.
To display an article in the Help Center navigation sidebar, you need to update the navigation.json file located inside the helpcenter repository.
The excerpt below shows an example of how the first articles in the Tutorials section are listed within this file:
{
{
"documentation": "Tutorials",
"slugPrefix": "docs/tutorial",
"categories": [
{
"name": {
"en": "Beta",
"es": "Beta",
"pt": "Beta"
},
"slug": {
"en": "category-beta-products",
"es": "categoria-beta-producto",
"pt": "categoria-produtos-beta"
},
"origin": "",
"type": "markdown",
"children": [
{
"name": {
"en": "Subscriptions Beta",
"es": "Suscripciones Beta",
"pt": "Assinaturas Beta"
},
"slug": {
"en": "subscriptions-beta",
"es": "suscripciones-beta",
"pt": "assinaturas-beta"
},
"origin": "",
"type": "category",
"children": [
{
"name": {
"en": "Subscription plans",
"es": "Planes de suscripción",
"pt": "Planos de assinatura"
},
"slug": {
"en": "subscription-plans",
"es": "planes-de-suscripcion",
"pt": "planos-de-assinatura"
},
"origin": "",
"type": "markdown",
"children": []
},
{
"name": {
"en": "Creating a subscription plan",
"es": "Cómo crear un plan de suscripción",
"pt": "Como criar um plano de assinatura"
},
"slug": {
"en": "creating-a-subscription-plan",
"es": "como-crear-un-plan-de-suscripcion",
"pt": "como-criar-um-plano-de-assinatura"
},
"origin": "",
"type": "markdown",
"children": []
}
]
},
...
}Follow the steps below to add new content to the navigation sidebar:
-
Open a feature branch in this repository.
-
In the navigation.json file, locate where you want the new article reference to appear in the side bar navigation menu.
-
Copy and paste the structure below into the JSON file, replacing the names of the articles (one version per locale) within the
nameobject, and the respective slugs in theslugobject.{ "name": { "en": "Creating a subscription plan", "es": "Cómo crear un plan de suscripción", "pt": "Como criar um plano de assinatura" }, "slug": { "en": "creating-a-subscription-plan", "es": "como-crear-un-plan-de-suscripcion", "pt": "como-criar-um-plano-de-assinatura" }, "origin": "", "type": "markdown", "children": [] } -
Save the file.
-
Commit the modifications as follows:
- Step 1: Go to the folder where
navigation.jsonis located.
cd public- Step 2: Stage the desired changes.
git add navigation.json
- Step 3: Commit the file.
yarn cz-commit
- Step 4: Move the cursor down to the
docs: Documentation only changesoption and click enter.
> docs: Documentation only changes- Step 5: Describe the purpose of this modification. This step can be skipped if desired.
? What is the scope of this change (e.g. component or file name): (press enter to skip)- Step 6: Briefly describe the changes made.
? Write a short, imperative tense description of the change (max 94 chars): Update the navigation bar to include the article "How to register a product in the catalog".
- Step 7: Describe in detail the changes made. This step can be skipped if desired.
? Provide a longer description of the change: (press enter to skip)- Step 8: Enter N to indicate that the modification is not a breaking change.
? Are there any breaking changes? (y/N)
- Step 9: Enter N to indicate that the modification does not affect any open issues.
? Does this change affect any open issues? (y/N)
- Step 10: Wait for the commit verification process to complete.
✔ Preparing lint-staged... ✔ Running tasks for staged files... ✔ Applying modifications from tasks... ✔ Cleaning up temporary files... [Test-navigation ec02017] docs: only test 1 file changed, 15 insertions(+) Done in 1237.38s.
- Step 11: Add a comment of your choice and push the commit.
git commit -m "navigation sidebar update" - Step 1: Go to the folder where
-
Open a PR on GitHub.
Important note: You should select the
release-nooption in theLabelsfield of the PR. -
Test your navigation through the preview.
-
Send the PR link in the
#dev-portal-prSlack channel to be approved. -
Once PR is approved, apply the merge to update the navigation sidebar.
ℹ️ For new information to appear in the Help Center, Education & Documentation team leaders must run the portal's build.
Redirect is the functionality that allows the browser to open a page with an address different from the one entered by the user in the URL field. This type of action is necessary when an old page address has been archived and a new one is created to replace it.
Follow the steps below to create a new redirect:
-
Open a feature branch in the repository.
-
In the netlify.toml file, you will find an array of redirects. Add the one you want to create following the format below, replacing
fromandtowith the desired slugs:[[redirects]] force = true from = "/es/topic/master-data" status = 308 to = "/tutorial/what-is-master-data--4otjBnR27u4WUIciQsmkAw"
ℹ️ Make sure you add specific redirects before more global redirects, otherwise they will have no effect. For now, hashlinks (
#) are not supported in the source slug. -
Save the file.
-
Commit the modifications as follows:
- Step 1: Stage the desired changes.
git add netlify.toml
- Step 2: Commit the file.
yarn cz-commit
- Step 3: Move the cursor to the
docs: Documentation only changesoption and click enter.
> docs: Documentation only changes- Step 4: Describe the purpose of this modification. This step can be skipped if desired.
? What is the scope of this change (e.g. component or file name): (press enter to skip)- Step 5: Briefly describe the changes made.
? Write a short, imperative tense description of the change (max 94 chars): Create redirect to article "How to edit a trade policy".
- Step 7: Describe in detail the changes made. This step can be skipped if desired.
? Provide a longer description of the change: (press enter to skip)- Step 8: Enter N to indicate that the modification is not a breaking change.
? Are there any breaking changes? (y/N)
- Step 9: Enter N to indicate that the modification does not affect any open issues.
? Does this change affect any open issues? (y/N)
- Step 10: Wait for the commit verification process to complete.
✔ Preparing lint-staged... ✔ Running tasks for staged files... ✔ Applying modifications from tasks... ✔ Cleaning up temporary files... [Test-navigation ec02017] docs: only test 1 file changed, 15 insertions(+) Done in 1237.38s.
- Step 11: Add a comment of your choice and push the commit.
git commit -m "redirect created" -
Open a PR on GitHub.
Important note: You should select the
release-nooption in theLabelsfield of the PR. -
Send the PR link in the
#dev-portal-prSlack channel to be approved. -
Once PR is approved, apply the merge to update the navigation sidebar.
-
Step 1. Create a feature branch based on
main(follow the naming pattern defined at Feature Branches section).git checkout main git checkout -b feature/nice-new-thing
-
Step 2. Develop the contribution in your feature branch by making commits (see How to make a commit section).
git add <filenames> git commit -m "feat: add nice new thing"
-
Step 3. Push your feature branch to the remote repository (in the following example represented by the origin alias)
git push origin feature/nice-new-thing
-
Step 4. Open a Pull Request (PR), select its reviewers and add it one of the release labels:
Release Labels Description Release Type release-noWhen no new version should be released when the PR is merged into the mainbranchNone release-autoWhen the new version to be released should be deducted automatically based on the PR semantic commits when it is merged [PATCH, MINOR, MAJOR] release-patchWhen the new version should be released as a patch PATCH release-minorWhen the new version should be released as a minor MINOR release-majorWhen the new version should be released as a major MAJOR -
Step 5. Verify if your Pull Request passed all checks that run against opened Pull Requests. In case any of them fails, look for a solution and update your feature branch.
Important note: If your branch has been updated with new commits, you should request new reviews to your PR.
-
Step 6. When your PR has been approved by reviewers, make sure your feature branch is still rebased on the
mainbranch. If it needs to be rebased, run:# Bring to local main branch the remote main latest updates git checkout main git pull origin main # Checkout your feature branch and rebase it onto main (solve possible conflicts) git checkout feature/new-nice-thing git rebase main # Force push your rebased feature branch git push --force origin feature/new-nice-thing
Go back to Step 5.
Important note: If your rebase process generated conflicts, new reviews must be requested.
-
Step 7. After your PR has been rebased onto
main, passed all checks and been approved by reviewers, click on Merge Pull Request option (the one that generates a merge commit). This way all commits from the feature branch will be added to the base branch and their semantic messages will be considered to updateCHANGELOG.mdwhen releasing a new version. -
Step 8. The merged PR, if set to release a new version in Step 4, will trigger a GitHub action that results in a new commit
chore(release): v*.*.*, a new version tag and its corresponding GitHub Release (see Versioning section for more details) - you can verify those changes in the repository initial page after the workflow has finished. Wait for the build in Netlify to end and your released version will be deployed. -
Step 9. Celebrate! You have just finished your contribution to the VTEX Help Center repository.
Make rebase of your feature branch on main:
# Bring to local main branch the remote main latest updates
git checkout main
git pull origin main
# Checkout your feature branch and rebase it onto main (solve possible conflicts)
git checkout feature/new-nice-thing
git rebase main
# Force push your rebased feature branch
git push --force origin feature/new-nice-thingImportant note: Always maintain your feature branch rebased on
main.