From f1e4323fda45c36301f4d820c28bf384cea74dd2 Mon Sep 17 00:00:00 2001 From: Jon Meow <46229924+jonmeow@users.noreply.github.com> Date: Tue, 16 Jun 2020 09:09:10 -0700 Subject: [PATCH] Set up pre-commit (#73) Added here: - .pre-commit-config.yaml - docs/project/contribution_tools.md - src/scripts/pre-commit-toc.js - CONTRIBUTING.md - proposals/* (just to switch TOC formats) The rest consists of auto-generated fixes. The switch from doctoc to markdown-toc is because doctoc wants to put a TOC in every file, whereas markdown-toc only does it if you have an insertion point. Co-authored-by: Chandler Carruth --- .github/workflows/publish-docs.yaml | 48 ++++++++++---------- .pre-commit-config.yaml | 33 ++++++++++++++ CONTRIBUTING.md | 12 ++++- docs/project/commenting_guidelines.md | 4 +- docs/project/contribution_tools.md | 64 +++++++++++++++++++++++++++ proposals/p0044.md | 5 +-- proposals/template.md | 13 ++++-- src/scripts/pre-commit-toc.js | 28 ++++++++++++ src/scripts/update-label-access.js | 0 9 files changed, 174 insertions(+), 33 deletions(-) create mode 100644 .pre-commit-config.yaml create mode 100644 docs/project/contribution_tools.md create mode 100755 src/scripts/pre-commit-toc.js mode change 100755 => 100644 src/scripts/update-label-access.js diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml index 9fb23f5cd52b..c4a87441f456 100644 --- a/.github/workflows/publish-docs.yaml +++ b/.github/workflows/publish-docs.yaml @@ -2,32 +2,32 @@ name: Publish Carbon Documentation on: push: branches: - - master + - master jobs: build: runs-on: [ubuntu-latest] steps: - - uses: actions/checkout@v2 - - uses: GoogleCloudPlatform/github-actions/setup-gcloud@master - with: - version: '285.0.0' - project_id: ${{ secrets.GCP_PROJECT_ID }} - service_account_email: ${{ secrets.GCP_SA_EMAIL }} - service_account_key: ${{ secrets.GCP_SA_KEY }} - export_default_credentials: true - - uses: actions/setup-ruby@v1 - with: - ruby-version: 2.6 - - run: gcloud info - - name: Install bundler - run: gem install bundler - working-directory: src/jekyll - - name: Install jekyll and dependencies - run: bundle install --jobs 4 --retry 3 - working-directory: src/jekyll - - name: Build HTML pages - run: make build - working-directory: src/jekyll - - name: Publish to www.carbon-lang.dev - run: gsutil cp -R src/jekyll/.gen-site/* gs://www.carbon-lang.dev/ + - uses: actions/checkout@v2 + - uses: GoogleCloudPlatform/github-actions/setup-gcloud@master + with: + version: '285.0.0' + project_id: ${{ secrets.GCP_PROJECT_ID }} + service_account_email: ${{ secrets.GCP_SA_EMAIL }} + service_account_key: ${{ secrets.GCP_SA_KEY }} + export_default_credentials: true + - uses: actions/setup-ruby@v1 + with: + ruby-version: 2.6 + - run: gcloud info + - name: Install bundler + run: gem install bundler + working-directory: src/jekyll + - name: Install jekyll and dependencies + run: bundle install --jobs 4 --retry 3 + working-directory: src/jekyll + - name: Build HTML pages + run: make build + working-directory: src/jekyll + - name: Publish to www.carbon-lang.dev + run: gsutil cp -R src/jekyll/.gen-site/* gs://www.carbon-lang.dev/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000000..6a1dee40d200 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,33 @@ +# See https://pre-commit.com for more information +# See https://pre-commit.com/hooks.html for more hooks +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v2.4.0 + hooks: + - id: check-added-large-files + - id: check-case-conflict + - id: check-executables-have-shebangs + - id: check-merge-conflict + - id: check-symlinks + - id: check-yaml + - id: detect-private-key + - id: end-of-file-fixer + - id: mixed-line-ending + args: ['--fix=lf'] + - id: trailing-whitespace + - repo: local + hooks: + - id: markdown-toc + name: markdown-toc + description: Runs https://github.com/jonschlinkert/markdown-toc + entry: src/scripts/pre-commit-toc.js + language: node + additional_dependencies: [markdown-toc] + files: .*\.md$ + exclude: ^src/jekyll/theme/ + # Prettier should be run late so that it can re-format any prior changes. + - repo: https://github.com/prettier/prettier + rev: 2.0.5 + hooks: + - id: prettier + exclude: ^src/jekyll/theme/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a039faad5ff8..a8d60ada9b82 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -184,6 +184,14 @@ follow the Carbon documentation and coding styles. - Keep in mind that code contribution guidelines are incomplete while we start work on Carbon, and may change later. +## pre-commit + +We use [pre-commit](/docs/project/contribution_tools.md#pre-commit) for +automated checks, including formatting of documentation. Please see +[contribution tools](/docs/project/contribution_tools.md) for more information. + +Please use pre-commit to simplify reviews. + ## Style ### Google Docs and Markdown @@ -191,8 +199,8 @@ follow the Carbon documentation and coding styles. Changes to Carbon documentation follow the [Google developer documentation style guide](https://developers.google.com/style). -Markdown files should additionally use [Prettier](https://prettier.io/) for -formatting. +Markdown files should additionally use +[Prettier](/docs/project/contribution_tools.md#prettier) for formatting. Other style points to be aware of are: diff --git a/docs/project/commenting_guidelines.md b/docs/project/commenting_guidelines.md index b059ffbe5189..3040d7b74b4e 100644 --- a/docs/project/commenting_guidelines.md +++ b/docs/project/commenting_guidelines.md @@ -25,7 +25,9 @@ always try to keep feedback, even when critical, constructive and supportive. - If your comment represents a significant change to the proposal, include a list of pros and cons. Even if the author disagrees with the change, they can use those to document the alternative. - - Feel free to extract long side discussions to a Discourse Forum topic, but make sure any important conclusions or outcomes are reflected in either the GitHub comments or the change itself. + - Feel free to extract long side discussions to a Discourse Forum topic, but + make sure any important conclusions or outcomes are reflected in either the + GitHub comments or the change itself. - **Be supportive in your criticism.** The author may be receiving many comments, and we want to keep contributors motivated to respond. diff --git a/docs/project/contribution_tools.md b/docs/project/contribution_tools.md new file mode 100644 index 000000000000..b58a83c78322 --- /dev/null +++ b/docs/project/contribution_tools.md @@ -0,0 +1,64 @@ +# Contribution tools + + + +The Carbon language project has a number of tools used to assist in preparing +contributions. + +## Table of contents + + + +- [pre-commit](#pre-commit) +- [markdown-toc](#markdown-toc) +- [Prettier](#prettier) + - [vim-prettier](#vim-prettier) + + + +## pre-commit + +We use [pre-commit](https://pre-commit.com) to run +[various checks](/.pre-commit-config.yaml). This will automatically run +important checks, including formatting. + +To set up pre-commit: + +- Follow the [installation instructions](https://pre-commit.com/#installation). +- Enable per-repo: `pre-commit install` + +When modifying or adding pre-commit hooks, please run +`pre-commit run --all-files` to see what changes. + +## markdown-toc + +**pre-commit enabled**: markdown-toc will be run by pre-commit, if installed. + +We use [markdown-toc](https://github.com/jonschlinkert/markdown-toc) to provide +GitHub-compatible tables of contents for some documents. + +If run manually, specify `--bullets=-` to use Prettier-compatible bullets, or +always run Prettier after markdown-toc. + +## Prettier + +**pre-commit enabled**: Prettier will be run by pre-commit, if installed. + +We use [Prettier](https://prettier.io/) for formatting. There is an +[rc file](/.prettierrc) for configuration. + +### vim-prettier + +If you use [vim-prettier](https://github.com/prettier/vim-prettier), it may help +to add to your `.virmc`: + +``` +let g:prettier#config#print_width = '80' +let g:prettier#config#tab_width = '2' +let g:prettier#config#use_tabs = 'false' +let g:prettier#config#prose_wrap = 'always' +``` diff --git a/proposals/p0044.md b/proposals/p0044.md index eb09b939fa97..5a70f0413e9b 100644 --- a/proposals/p0044.md +++ b/proposals/p0044.md @@ -12,8 +12,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception ## Table of contents - - + - [Problem](#problem) - [Background](#background) @@ -67,7 +66,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception - [StackEdit](#stackedit) - [GitHub Markdown syntax highlighting](#github-markdown-syntax-highlighting) - + ## Problem diff --git a/proposals/template.md b/proposals/template.md index 3b28235ad9d5..3c312632e31c 100644 --- a/proposals/template.md +++ b/proposals/template.md @@ -12,9 +12,16 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception ## Table of contents - - - + + +- [TODO: Initial proposal setup](#todo-initial-proposal-setup) +- [Problem](#problem) +- [Background](#background) +- [Proposal](#proposal) +- [Details](#details) +- [Alternatives considered](#alternatives-considered) + + ## TODO: Initial proposal setup diff --git a/src/scripts/pre-commit-toc.js b/src/scripts/pre-commit-toc.js new file mode 100755 index 000000000000..ac633b33a270 --- /dev/null +++ b/src/scripts/pre-commit-toc.js @@ -0,0 +1,28 @@ +#!/usr/local/bin/node + +/* +Part of the Carbon Language project, under the Apache License v2.0 with LLVM +Exceptions. See /LICENSE for license information. +SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +*/ + +/* +Runs markdown-toc for pre-commits. This is necessary to handle multiple file +arguments, which markdown-toc does not. + +Humans should generally use markdown-toc following the install instructions +from https://github.com/jonschlinkert/markdown-toc. +*/ + +const mdtoc = require('markdown-toc'); +const fs = require('fs'); + +const files = process.argv.slice(2); +for (var i = 0; i < files.length; ++i) { + const oldContent = fs.readFileSync(files[i]).toString(); + const newContent = mdtoc.insert(oldContent, { bullets: '-' }); + if (oldContent != newContent) { + console.log(`Updating ${files[i]}`); + fs.writeFileSync(files[i], newContent); + } +} diff --git a/src/scripts/update-label-access.js b/src/scripts/update-label-access.js old mode 100755 new mode 100644