Skip to content

Home

Jump to bottom
Sam Richard edited this page May 13, 2024 · 8 revisions

We just launched a ground-up refactor of this site. This wiki may be out of date while we're updating our documentation to match our new codebase

Thanks for your interest in contributing to ChromeOS.dev! The following topics will help guide you towards the best place to provide feedback, how to work with us on GitHub, and how to build and run the site locally. Once you're set up, be sure to check out our folder structure to learn where everything goes and our coding standards to learn our best practices for writing code.

  1. Improve Chrome OS or ChromeOS.dev
    1. Tracking progress
  2. Local development
    1. Prerequisites & dependencies
      1. Installing Node dependencies
    2. Running locally
      1. Other useful commands
    3. Automated tests
      1. Linting
      2. Unit tests
      3. Visual regression tests
  3. Primary tools
    1. Build tools and languages
    2. Testing and linting tools

Improve Chrome OS or ChromeOS.dev

Thanks for your feedback! For Chrome OS, please file a defect on the Chromium bug tracker and follow-up there for updates. For ChromeOS.dev, file an issue and a team member should reply shortly. Please follow these best practices when filing an issue here for us:

  • Please create or follow-up on an issue, and have a discussion with a maintainer about the issue in the issue, before filing a PR.
  • Please include as much information as possible about your browsing context when filing a bug report
  • Be respectful of the maintainers' time and other priorities.

While we appreciate all feedback, please understand that accepting changes, especially creating new content or changing existing content, is at the maintainers' discretion.

Tracking progress

While not required to provide feedback, we track progress of issues in GitHub using ZenHub. With the ZenHub extension installed, you can see our bug and feature progress or our content progress on our board.

Local development

In order to build our site locally, you need to start by forking and cloning this repository. Once cloned, make sure you have the prerequisites installed and that you install the site dependencies. When your environment is good to go, you can build and run the site locally.

Prerequisites & dependencies

Both the site and functions require Node.js 14. In order to install and manage different versions of Node, we recommend installing a node version manager; we like Volta for its speed and simplicity. Once Volta is installed, it will automatically install, if needed, and use the correct versions of Node when you try and run any Node commands in our project. You can make sure you're on the right Node version by running node -v. If you accidentally built with an incorrect version of node, first install the correct version of node. Once you have the correct version of remove the node_modules directory and try running npm install again.

Installing Node dependencies

With Node installed and this repo forked and cloned, it's time to install the site's dependencies. Open the cloned repository's folder in your command line and run npm ci to install dependencies. Be sure to run that command in the functions folder, too.

Running locally

Once you have everything installed, you can run a local development server and preview the site. To do so, open the cloned repository's folder in your command line and run npm start. This command will open a local preview of the site in your default browser, as well as let you make changes to files and have it automatically reload the browser.

Other useful commands

Our package.json file contains a number of scripts that can be run as NPM commands, but most are not meant to be run on their own. The following NPM commands (npm run COMMAND) are meant to be run on their own, should you need:

  • build - Run a full production build of the site
  • lint - Lint all files
  • test - Run all tests
  • start - Start a local development server, watch for changes, and reload the browser when changes occur.

Automated tests

The codebase includes a number of automated tests as well as linting. The easiest way to run all of them is by running npm test, which will run linting first.

Linting

The codebase includes JavaScript linting, Markdown linting, Sass linting, and Prettier style linting. Linting is run before any git push and staged files are linted before being committed is allowed to proceed. Linting can be run directly by running npm run lint.

Unit tests

Unit tests can be found in the tests directory and are run via AVA. Unit tests should cover code in the lib directory and the src/js directory (although we currently lack a browser testing solution, so there aren't many src/js tests).

Visual regression tests

Visual regression references can be found in the .backstop/references directory and are run via BackstopJS, with the runner code in vrt.js. VRTs are based on the production build of the site, so be sure to run npm run build before trying to run the visual regression tests for the best chances of them passing. Visual regression references should be made off of mostly static pages, like style guide pages, and should not include animated elements as it's difficult to properly account for animation. If there are discrepancies between the tests and the references, you can run npm run vrt:serve to view the HTML report and review the differences. If all of the differences are expected and you want to promote them to references, run npm run vrt:approve. Visual regression tests can be run directly by running npm run vrt. These tests are not currently run because of variance we see in our continuous integration platform, and therefore may be out-of-date.

Primary tools

The tools we use can be broken down into two types, build tools and test tools. We recommend you install syntax highlighting for each language/template type we use and plugins for each test tool (especially linting and code formatting tools) for your code editor to aid you as you develop.

Build tools and languages

  • Eleventy - The primary tool to compile our templates and markdown into HTML. Our codebase is set up around it and we make some pretty heavy use of some of its more advanced features.
    • Nunjucks - Our templating language. While Eleventy supports many templating languages, we exclusively use Nunjucks.
    • Markdown-It - Our Markdown compiler, extended with a number of plugins and using Prism for syntax highlighting.
  • Sass - CSS meta-language and compiler. Specifically using the .scss syntax for all code.
  • Vite - All-around site build tool. We aren't transforming our JavaScript apart from dynamic imports. Our JavaScript is delivered as modules client-side (except for the Service Worker), so any code written must work in all browsers that support JavaScript modules or have a polyfill manually provided.
  • PostHTML - HTML transformations

Testing and linting tools

PR Titles

PR titles should be formatted as follows:

{emoji}({section}) {title}

Where emoji and title are required, and section is optional.

Emoji Meaning
🐎 Improve performance
🐛 Fix bug
🆕 Add new feature
📝 Add or update docs or content
♻️ Refactor
📌 Pin dependencies
💎 Improve code style
Section Meaning
site Pertaining to the site (HTML, CSS, JS) served to users
build Pertaining to the build system, including CI
test Pertaining to tests, including linting
functions Pertaining to the serverless functions
content Pertaining to site content
Clone this wiki locally