Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _layouts/docs.liquid
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ editable: true
</p>
<p class='doc-terms'>
{%- if google %}
Portions of this page are reproduced from work
Portions of this page are adapted from work
<a
href='https://developers.google.com/site-policies'
rel='nofollow noopener noreferrer'
Expand Down
8 changes: 4 additions & 4 deletions build/shared/commit-message.mts
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ export const TRAILER_ORDER = [
];

/** U+FF1A, which separates the emoji from the description. */
const IDEOGRAPHIC_COLON = ':';
const FULLWIDTH_COLON = ':';

/** The invisible character that distinguishes two spellings of one emoji. */
const EMOJI_SELECTOR = '️';
Expand Down Expand Up @@ -186,15 +186,15 @@ export function readTrailers(message: string) {
*/
const checkSubject = (subject: string) => {
const problems: string[] = [];
const colon = subject.indexOf(IDEOGRAPHIC_COLON);
const colon = subject.indexOf(FULLWIDTH_COLON);

if (colon === -1) {
problems.push(
`subject needs an emoji prefix and “${IDEOGRAPHIC_COLON}” (U+FF1A), as in “🏗️🔧${IDEOGRAPHIC_COLON}fix the thing”`
`subject needs an emoji prefix and “${FULLWIDTH_COLON}” (U+FF1A), as in “🏗️🔧${FULLWIDTH_COLON}fix the thing”`
);
} else {
const prefix = subject.slice(0, colon);
const description = subject.slice(colon + IDEOGRAPHIC_COLON.length);
const description = subject.slice(colon + FULLWIDTH_COLON.length);
// The variation selector belongs to the character before it, so the
// prefix has to be read as grapheme clusters and not code points.
const clusters = [...SEGMENTER.segment(prefix)].map(
Expand Down
2 changes: 1 addition & 1 deletion build/shared/commit-message.test.mts
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ describe('validateCommitMessage: the subject', () => {
deepStrictEqual(validateCommitMessage('📖:write it down'), []);
});

test('wants the ideographic colon', () => {
test('wants the fullwidth colon', () => {
match(soleProblem('🏗️🔧: fix the thing'), /U\+FF1A/);
});

Expand Down
6 changes: 3 additions & 3 deletions collections/_docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@

<br /><br />

### Install Dependencies
### Install dependencies

<br />

Expand All @@ -29,7 +29,7 @@ pnpm install

<br /><br />

### Running Locally
### Running locally

One can preview contributions before opening a pull request.

Expand Down Expand Up @@ -81,7 +81,7 @@ credit, so a page carrying any of it says where it came from:
```yaml
---
title: Colons
key_point: A colon indicates that closely-related information follows.
key_point: A colon indicates that closely related information follows.
google: true
---
```
Expand Down
38 changes: 19 additions & 19 deletions collections/_docs/agent-forwarding.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ works today and what to do when it doesn't.
The devcontainer changed substantially in [#1775][]: it no longer runs its own
`sshd` on a forwarded port, and there is no more `vscode` user or manual
`RemoteForward` tunnel to configure. Everything below reflects that container.
If you find instructions elsewhere -- including an old revision of this file --
If you find instructions elsewhere — including an old revision of this file —
mentioning port 2222 or a `gpgtunnel` SSH host, they predate that change and no
longer apply.

Expand All @@ -25,7 +25,7 @@ longer apply.
VS Code (and compatible tools like the Dev Containers CLI) forwards your
_running_ SSH agent into the container automatically; no devcontainer.json
configuration is required for it. What it does **not** do is copy any key
material in -- not the private key, and, for SSH-format signing, not even the
material in — not the private key, and, for SSH-format signing, not even the
public key file. See VS Code's own docs on [sharing Git credentials][] for the
authoritative description.

Expand All @@ -39,22 +39,22 @@ That gap matters because of how the two signing formats differ:
`ssh-keygen -Y sign -f <user.signingkey> ...`. That `-f` argument is a **file
path**, and `user.signingkey` in a gitconfig copied from your host points at a
host path (typically `~/.ssh/id_ed25519.pub`) that has never existed in the
container. The forwarded agent doesn't help until that file exists -- and the
container. The forwarded agent doesn't help until that file exists — and the
container's non-root user usually can't even create it: a Mac's `/Users/<you>`
or a Linux host's `/home/<you>` both live under a root-owned directory this
container's `node` user has no write access to, so recreating the host's path
byte-for-byte fails with a permissions error regardless of host OS.

`.devcontainer/post-start.sh` closes that second gap. It runs on every container
**start/attach**, unlike `post-create.sh`, which only ever runs once, when the
container is first built -- too early, since the forwarded agent socket is a
container is first built — too early, since the forwarded agent socket is a
fresh, per-session thing set up on each attach. If `gpg.format` is `ssh` and the
forwarded agent is holding exactly one identity, `post-start.sh` writes that
public key to a path under `$HOME/.ssh` in the container (not the host path
copied into `user.signingkey`) and repoints the container's own
`user.signingkey` at it. It deliberately does nothing if the agent has zero
identities (nothing to write) or more than one (no reliable way to know which
one you mean) -- watch its output on attach to see which case you're in.
one you mean) — watch its output on attach to see which case you're in.

Either way, the actual cryptographic signing still happens on the host, via the
forwarded agent. No private key material is ever copied into the container.
Expand Down Expand Up @@ -86,7 +86,7 @@ and involves nothing on your machine.
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
```

- Point Git at it. Run this **on the host**, in a host terminal -- the container
- Point Git at it. Run this **on the host**, in a host terminal — the container
gets its own copy of `~/.gitconfig` at build time, so running it inside the
container configures only the container and silently leaves the Mac unchanged:

Expand All @@ -99,14 +99,14 @@ and involves nothing on your machine.
- Reopen or rebuild the devcontainer and watch `post-start.sh`'s output on
attach. `Commit signing ready` means the public key was found in the forwarded
agent and written into the container. Anything else means the agent forwarded
into _this_ session doesn't have exactly one identity -- check `ssh-add -l` on
into _this_ session doesn't have exactly one identity — check `ssh-add -l` on
the host first.

Use an ordinary `ssh-keygen`-generated key pair here. Keys that exist only
inside a Secure Enclave or an external agent, with no public key file on disk,
are a poor fit: `user.signingkey` has to name a real path on the host, and
`post-start.sh` needs a public key it can write out in the container. The two
paths don't need to match -- `post-start.sh` retargets the container's own copy
paths don't need to match — `post-start.sh` retargets the container's own copy
of `user.signingkey` to wherever it actually writes the file, under
`$HOME/.ssh`.

Expand All @@ -128,7 +128,7 @@ to verify it, which is a separate mechanism that can fail on its own. See
## Verifying signatures locally

Verification is a distinct mechanism from signing, with its own configuration
and its own failure modes -- a commit can be perfectly signed and still fail to
and its own failure modes — a commit can be perfectly signed and still fail to
verify here. For SSH-format signatures, Git needs an [allowed signers][] file
mapping each principal (an email address) to the keys it may sign with. Unlike
GPG, where the keyring is discovered automatically, Git has no default location
Expand All @@ -150,7 +150,7 @@ Two things it deliberately does not attempt:
to this address. That makes local verification meaningful for catching a
misconfigured or swapped key; it is not third-party attestation the way
GitHub's "Verified" badge is. GitHub does its own check against the keys
registered on your account -- see its docs on [commit signature
registered on your account — see its docs on [commit signature
verification][], and note that a key has to be added as a **signing** key
there, separately from the same key added for authentication.

Expand All @@ -165,7 +165,7 @@ error: gpg.ssh.allowedSignersFile needs to be configured and exist
No signature
```

`No signature` here is the verifier reporting that it could not run -- not a
`No signature` here is the verifier reporting that it could not run — not a
statement about the commit, which may well be signed. The wording invites the
opposite reading, and acting on it means re-checking `commit.gpgsign`,
`user.signingkey` and the agent, all of which were fine. Confirm with
Expand Down Expand Up @@ -193,9 +193,9 @@ If you use an actual OpenPGP key instead:

## Troubleshooting

- **`ssh-add -l` says "The agent has no identities"** -- this is a host-side
- **`ssh-add -l` says "The agent has no identities"** — this is a host-side
fact, not a container problem. Add the key on the host and reattach.
- **`post-start.sh` reports more than one identity** -- it won't guess. Either
- **`post-start.sh` reports more than one identity** — it won't guess. Either
unload the extra identities from the agent for this session, or, inside the
container, write the file yourself from the one you mean, then point
`user.signingkey` at it:
Expand All @@ -205,27 +205,27 @@ If you use an actual OpenPGP key instead:
git config --global user.signingkey ~/.ssh/id_ed25519.pub
```

- **It worked before, stopped working after a container rebuild** -- the signing
- **It worked before, stopped working after a container rebuild** — the signing
key and `allowed_signers` files `post-start.sh` writes, and the
`user.signingkey`/`gpg.ssh.allowedSignersFile` overrides pointing at them, all
live in the container's filesystem, not a volume, so a rebuild removes them
along with the host's copied-in gitconfig. Everything gets rewritten on the
next attach as long as the agent still has exactly one identity at that point.
- **`post-start.sh` says "Signature verification NOT configured: no
user.email"** -- it needs `user.email` to know which principal to list against
user.email"** — it needs `user.email` to know which principal to list against
your key in `allowed_signers`, and won't guess one. Set it (globally, on the
host, same as the other signing settings) and reattach:

```console
git config --global user.email you@example.com
```

- **`git log --show-signature` says `No signature`** -- establish that the
commit is actually unsigned before treating it as a signing problem, since
that message is also what a verifier that could not run prints.
- **`git log --show-signature` says `No signature`** — establish that the commit
is actually unsigned before treating it as a signing problem, since that
message is also what a verifier that could not run prints.
`git cat-file commit HEAD` settles it; see
[above](#when-show-signature-says-no-signature).
- **Everything looks configured, but commits still come out unsigned** -- check
- **Everything looks configured, but commits still come out unsigned** — check
for a per-repository override before re-checking anything global:

```console
Expand Down
111 changes: 105 additions & 6 deletions collections/_docs/handbook/style/capitalization.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,113 @@
---
title: Capitalization
key_point: When to capitalize, and when to leave a word lowercase.
stub: true
---

> [!NOTE]
>
> This page is a placeholder. It is linked from elsewhere in the handbook and is
> yet to be written.
Capitalize a name. Leave everything else alone. Most disagreements about
capitalization are really disagreements about whether a thing is a name, and
answering that question settles the spelling.

A capital letter is a claim that a word is the name of one particular thing.
Applying it to an ordinary noun — a feature, a format, a role — asks the reader
to look for a proper noun that is not there.

## Capitalization in headings

Yet to be written.
A page title is set in title case, capitalizing the first word, the last word,
and everything between them except articles, coordinating conjunctions, and
prepositions.

<p class="example">
<span class="compare-better">Recommended:</span> Documenting Command-Line
Syntax
</p>
<p class="example">
<span class="compare-worse">Not recommended:</span> Documenting command-line
syntax
</p>

The exceptions are what the rule turns on. A preposition in the middle of a
title stays lowercase however long the title is:

<p class="example">
<span class="compare-better">Recommended:</span> Code in Text
</p>
<p class="example">
<span class="compare-worse">Not recommended:</span> Code In Text
</p>

A heading inside a page is set in sentence case: the first word capitalized, and
after that only what would be capitalized in running text.

<p class="example">
<span class="compare-better">Recommended:</span> Explaining placeholders
</p>
<p class="example">
<span class="compare-worse">Not recommended:</span> Explaining Placeholders
</p>

An adapted page follows these rules too. A page that carries an attribution line
says where its wording came from, not whose house style it is set in, and a
reader moving between pages should not be able to tell which is which from the
headings.

## The name of the project

The project is **OpenINF**. One capital at the front for _Open_, three at the
back for _INF_, and nothing else.

<p class="example">
<span class="compare-better">Recommended:</span> OpenINF
</p>
<p class="example">
<span class="compare-worse">Not recommended:</span> OPENINF, Openinf, openINF
</p>

Setting the name in full capitals is shouting it, and a name that shouts in
running text is a name the reader learns to skip. This holds in headings, in
navigation, and in the small print at the foot of a page — nowhere is it
`OPENINF`.

The scope on npm is lowercase, because npm scopes are lowercase: `@openinf`.
Write a package name exactly as it is published, in code font, and never
capitalize it to start a sentence. Rewrite the sentence instead.

<p class="example">
<span class="compare-better">Recommended:</span> The
<code>@openinf/util-types</code> package has no dependencies.
</p>
<p class="example">
<span class="compare-worse">Not recommended:</span>
<code>@openinf/util-types</code> has no dependencies.
</p>

## Words that only look like names

Technologies, formats, and general concepts are ordinary nouns. They take a
capital only where a name is embedded in them.

| Write | Not |
| :------------------- | :------------------- |
| open source | Open Source |
| the web | the Web |
| the internet | the Internet |
| a pull request | a Pull Request |
| the command line | the Command Line |
| JavaScript, npm, Git | Javascript, NPM, git |

The last row is the exception that proves the rule: those three are names, and
each has one correct spelling that is neither all lowercase nor all capitals.

## After a colon

A colon does not start a new sentence, so what follows it is capitalized only if
it would be capitalized anywhere else. See [Colons][] for when the colon is the
right mark at all.

<!-- prettier-ignore-start -->
<!-- LINK DEFINITION LABELS - START -->

[Colons]: https://open.inf.is/docs/handbook/style/colons/

<!-- LINK DEFINITION LABELS - END -->
<!-- prettier-ignore-end -->
Loading
Loading