# Conventional Commits: the spec repo, and how to run its site locally > The conventionalcommits.org repository holds the Conventional Commits 1.0.0 specification plus a Hugo site that publishes it in every translation. Here is what the spec actually defines, how to build the site with docker-compose, and where the spec stops and your tooling has to start. **conventional-commits/conventionalcommits.org** — The conventional commits specification - Repository: https://github.com/conventional-commits/conventionalcommits.org - Website: https://conventionalcommits.org - Stars: 9,281 · Forks: 696 - Language: SCSS - License: MIT - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/conventional-commits-conventionalcommits-org ## What the Conventional Commits repository actually contains This is not a library. The repository is the home of the Conventional Commits specification, and the README states that plainly. The primary language listed for the repository is SCSS, which tells you where the bulk of the hand-written code sits: in the theme that renders the site, not in any parser. The top-level entries confirm the shape of the project. There is a config.yaml for Hugo, a content/ directory, layouts/, static/, and themes/. There is no src/ directory holding a commit parser, and the README documents no API. The specification itself lives under content/. The README says content/next/ holds the version where all changes should be made, and that files named index.[lang].md are translations. So the canonical text of version 1.0.0 sits alongside a working copy for the next revision, and every language is a separate markdown file in the same directory tree. If you came here looking for code to install into your project, you are in the wrong repository. If you came here to understand the format your release tooling expects, or to fix a typo in a translation, you are in the right one. ## The commit format the specification defines The badge in the README pins the version: Conventional Commits 1.0.0. The format is a commit message structured so that a machine can read the intent of a change without reading the diff. A type prefix, an optional scope in parentheses, an optional breaking-change marker, then a description. The specification is what tools such as conventional-changelog consume when they generate a changelog or decide whether a release is a patch, a minor or a major. That last point is the reason the format exists. If a commit declares a breaking change, a release tool can bump the major version without a human deciding. If it declares a feature, the tool bumps the minor. The specification is short by design, and the repository reflects that. The README is mostly about the website, not about the grammar. Anyone expecting a formal grammar or a conformance suite in this repository will not find one; the specification prose is the artefact, and the site is how it is delivered. ## Running the specification site locally with docker-compose The README gives one supported path for local work: a docker-compose.yml file that builds the site and serves it. The README says to install docker-compose and then run a single command. The compose file maps port 1313 on the host to port 1313 in the container, sets the working directory to /src/, and bind-mounts the repository into the container so edits on disk appear without a rebuild. ```bash docker-compose up ``` The README states that once the website is compiled you can view it at http://localhost:1313. The build uses Dockerfile.dev, which is the development variant referenced by the compose file. If you prefer to work without Docker, the Makefile exposes the underlying steps. The all target runs compile-assets and compile-site in sequence, and serve-site-dev runs hugo serve bound to 0.0.0.0. ```bash make all-dev ``` That target compiles the theme assets and starts the Hugo development server. The compile-assets step changes into themes/conventional-commits, runs npm install and npm run build, which is where the SCSS is processed. The production Dockerfile takes a different route: it builds the theme assets in a node:19.0.0-alpine stage, builds the site with jguyomard/hugo-builder, and copies the generated public/ directory into an nginx image that exposes port 80. Nothing in the README documents the Node version requirement beyond the .node-version file in the repository root. ## Adding a translation, and the friction in that workflow The README describes the translation process in three steps: create a new file under content/version/ using the hugo new command, fill in the front matter fields by copying an existing file, and register the language in config.yaml. The hugo new invocation is given as hugo new [version]/index.[lang].md, so a new locale needs both a directory matching the version and a filename carrying the language code. The friction is that the specification text is duplicated per language, with no translation memory and no automated check that a translation stays in sync with the English source when the next version changes. A translator working on content/next/ has to diff against the English file by hand. That is a deliberate simplicity, and it keeps the site build trivial, but it means translation drift is a maintenance cost the repository does not solve for you. The README also asks contributors to keep all changes in content/next/, which is the only place the project wants edits to land before a version is cut. ## What the specification does not give you The most common wrong assumption about this project is that cloning it gets you enforcement. It does not. The README documents no commit-msg hook, no linter, no CI configuration for validating commit messages, and no CLI. The repository is a specification plus a website, and the README's contribution section is about refining language, fixing typos and adding translations, not about tooling. Two consequences follow. First, nothing in this repository will reject a malformed commit; you need a separate tool for that, and the specification is the contract that tool implements. Second, the specification does not define a controlled vocabulary for types or scopes. It gives the shape of the message and leaves the values to each project. That is a feature for adoption and a problem for consistency: two teams following the same specification can produce commit histories that no shared changelog configuration handles without adjustment. If you need a fixed type list, that decision lives in your project's contributing guide, not here. ## Where this fits against a commit linting tool The obvious alternative to reading this specification is to install a commit message linter and let it define the rules for you. The two are not competitors in the usual sense, but the difference in approach matters. A linter ships an opinionated default configuration: a fixed set of types, a header length limit, a scope policy. It tells you what a valid message is by rejecting invalid ones. This specification does the opposite. It describes the grammar and leaves the vocabulary open, which is why the same format can serve a JavaScript monorepo and a Go service without either project changing the specification. If you adopt the specification directly, you own the decisions about types and scopes and you own the enforcement. If you adopt a linter, you inherit someone else's decisions and get enforcement for free. Teams that want a changelog tool to work out of the box usually want the second; teams writing their own release automation usually want the first, because the specification is the stable part and the vocabulary is theirs. ## Licence, maintenance and the cost of tracking the specification The repository is MIT licensed, and the LICENSE file sits at the top level. For most readers this is a formality: you are reading a specification and copying a badge, not redistributing code. The MIT terms are permissive, and the README explicitly invites you to tell your users that you use the specification by pasting the badge markdown it provides. If you fork the site theme or reuse the SCSS, the licence permits it with attribution. This is not legal advice, and if you plan to republish the specification text commercially you should read the LICENSE file yourself. The last push to the repository was on 2026-03-11. That is recent enough that the project is not dormant, but the specification itself is versioned at 1.0.0 and the README points contributors at content/next/ for future changes, which suggests the text is stable rather than fast-moving. The upgrade cost for a consumer is close to zero: you pin the badge to 1.0.0, your tooling implements the 1.0.0 grammar, and a future revision is something you read about rather than something you install. The upgrade cost for a contributor is the translation sync problem described above, plus keeping the Hugo theme's Node dependencies current. ## Conclusion Adopt the specification if you want commit history that machines can parse for changelogs and semantic version bumps, and clone this repo only when you intend to edit the spec text or a translation. Do not expect the repository to give you a linter, a changelog generator or a commit hook; it is a specification and a website, and the README points at no tooling. Before you commit to the format, verify two things in your own project: that your release tooling reads the type and scope fields the way the spec describes, and that your team agrees on a scope vocabulary, because the specification deliberately does not define one. ## FAQ ### What is a conventional git commit? It is a commit message written in the format defined by the Conventional Commits specification, whose 1.0.0 version is published by this repository. The format gives the message a machine-readable structure so release tooling can derive changelogs and version bumps from the commit history. ### How do I see a list of commits? The repository material does not cover inspecting commit history; it covers the specification text and the Hugo site that publishes it. The README's local instructions are about running the website, not about querying git history. ### What is the 50/72 rule? The material for this repository does not describe a 50/72 rule. The specification published here defines the structure of a commit message, and the README does not state a subject or body line length limit. ### What are Conventional Commits tests? The repository does not document a conformance test suite for the specification. It contains the specification versions under content/ and the Hugo site that renders them, and the README describes contribution as refining language, fixing typos and adding translations. ## Sources - [conventional-commits/conventionalcommits.org on GitHub](https://github.com/conventional-commits/conventionalcommits.org) - [Issues](https://github.com/conventional-commits/conventionalcommits.org/issues) - [License: MIT](https://github.com/conventional-commits/conventionalcommits.org/blob/master/LICENSE) - [Project website](https://conventionalcommits.org) - [README](https://github.com/conventional-commits/conventionalcommits.org/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/conventional-commits-conventionalcommits-org