Developers Portal

Summary

About
Versioning
Tests
Development
GitHub Actions
Contributing
- How to develop and propose a new contribution
- What to do when someone updated the main branch and I'm developing something on my feature branch

About

Objective

This repository implements the new VTEX Developers Portal with better navigability, content centralization and search facility to improve developers experience as they consult our applications documentation, guides and API references.

Concepts and Features

As the Developer Portal provides VTEX documentation to users, some of its main features are:

OpenAPI documentations rendering

The OpenAPI specification was chosen by VTEX to generate its API references guides since it defines a standard interface to describe RESTful APIs, as well as it can be easily understood, consumed and rendered by tools like ReadMe (used in the initial Developers Portal).
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. VTEX developers and many tech writers reccur to Markdown to write documentation, including those served by the Developers Portal.
GitHub API Integration with Rate Limit Handling

The portal uses GitHub's API through Octokit to fetch documentation content. To handle GitHub API rate limits gracefully:
- Configurable retry mechanism with max retries and timeout
- Automatic fallback to raw.githubusercontent.com when API limits are hit
- Smart throttling to prevent excessive API calls

Caching Structure for Technical Writers

The Developer Portal uses Netlify's CDN and caching infrastructure to optimize performance. When updating documentation, technical writers should be aware of how caching affects the visibility of their changes:

OpenAPI Documentation Caching

When you update an OpenAPI specification file in the GitHub repository:

Cache Duration:
- Updated specs will be visible after the cache expires, typically:
  - Primary source (jsdelivr): 5 minutes (300 seconds)
  - Fallback source (GitHub raw): 3 minutes (180 seconds)
- A stale-while-revalidate period of up to 15 minutes may follow
Cache Invalidation Options:
- Automatic Expiration: Wait for the cache to naturally expire (~5 minutes)
- Manual Purging: For urgent updates, you can request cache purging via Netlify's Cache Purge API using cache tags:
```
curl -X POST "https://api.netlify.com/api/v1/sites/{site-id}/builds/cache" \
  -H "Authorization: Bearer {access-token}" \
  -H "Content-Type: application/json" \
  -d '{"cache_tags": ["openapi,spec-name"]}'
```
Debugging Cache Status:
- The API response includes debugging headers to help track cache status:
  - X-Source: Shows which source provided the spec (jsdelivr or github-raw)
  - X-References-Resolved: Indicates if spec references were resolved
  - X-Cache-Debug: Contains source, resolution status, and TTL information
Testing Updates:
- To verify changes immediately without waiting for cache expiration:
  - Add a unique query parameter to force a cache miss: ?v=timestamp
  - Request cache purging from your development team

Understanding this caching structure helps set appropriate expectations for when documentation updates will become visible to users.

Versioning

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.md and package.json version updates based on semantic commit messages, as well as the creation of new version tags

Standard Version provides a release script that results in a release commit containing a new version in package.json and updates in CHANGELOG.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 main branch

A GitHub action named Release Version Workflow is triggered whenever a PR is merged into the main branch. The action's workflow is represented by the diagram below, its steps identify whether the PR should release a new version - and of what type - to run the release script, push its results and generate a new GitHub Release corresponding to the new version 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)

Tests

Performance tests on desktop and mobile devices

Lighthouse is a tool that analyzes web apps and web pages to collect performance metrics and insights on developer best practices. To avoid significant performance drops introduced by Pull Requests, a pair of GitHub actions using Lighthouse CI are running against PRs to collect the performance metrics of the code with the proposed changes at desktop and mobile devices (a report containing the results is hosted on a URL that is availaible at the end of the actions log).
Automated tests

Cypress is an automated testing tool that was added to the repository so pre-defined E2E or unitary tests (inside cypress directory) will be executed whenever a PR is opened.

Cypress Tests

The Cypress tests are designed to ensure the functionality and stability of the Developers Portal. The tests cover four main areas:

Documentation Pages Status Tests
- Randomly selects and verifies the loading status of documentation pages
- Includes retry mechanisms for both run mode (3 retries) and open mode (3 retries)
- Logs any failed page checks for debugging purposes
API Reference Documentation Tests
- Verifies sidebar functionality:
  - Tests the collapse/expand button behavior
  - Confirms sidebar visibility states
- Tests navigation:
  - Verifies random guide page loading through sidebar navigation
  - Ensures proper URL patterns for API reference pages
- Validates content:
  - Checks for presence of API documentation title
  - Tests response tab functionality and content visibility
API Guides Documentation Tests
- Verifies sidebar functionality:
  - Tests the collapse/expand button behavior
  - Confirms sidebar visibility states
- Tests navigation:
  - Verifies random guide page loading through sidebar navigation
  - Ensures proper URL patterns for guide pages
- Validates content and features:
  - Checks for presence of guide titles
  - Tests document contributor links (verifies GitHub redirects)
  - Validates feedback system:
    - Tests feedback section visibility
    - Verifies feedback modal functionality
    - Tests feedback submission process
  - Tests table of contents navigation:
    - Verifies all headi

Devportal

Install / Use

README