From b5c63f68687f51160b87649ebb5adeec1998a3c5 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 17 Oct 2023 10:29:18 -0500 Subject: [PATCH] docs(contrib): Policy on manifest editing Based on https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/Automatic.20edits.20to.20.60Cargo.2Ctoml.60 --- src/doc/contrib/src/SUMMARY.md | 1 + .../contrib/src/implementation/formatting.md | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 src/doc/contrib/src/implementation/formatting.md diff --git a/src/doc/contrib/src/SUMMARY.md b/src/doc/contrib/src/SUMMARY.md index f8796b3f33a..268d8b6401f 100644 --- a/src/doc/contrib/src/SUMMARY.md +++ b/src/doc/contrib/src/SUMMARY.md @@ -14,6 +14,7 @@ - [New subcommands](./implementation/subcommands.md) - [Console Output](./implementation/console.md) - [Filesystem](./implementation/filesystem.md) + - [Formatting](./implementation/formatting.md) - [Debugging](./implementation/debugging.md) - [Tests](./tests/index.md) - [Running Tests](./tests/running.md) diff --git a/src/doc/contrib/src/implementation/formatting.md b/src/doc/contrib/src/implementation/formatting.md new file mode 100644 index 00000000000..91321f1a50d --- /dev/null +++ b/src/doc/contrib/src/implementation/formatting.md @@ -0,0 +1,17 @@ +# Formatting + +When modifying user files, like `Cargo.toml`, we should not change other +sections of the file, +preserving the general formatting. +This includes the table, inline-table, or array that a field is being edited in. + +When adding new entries, they do not need to match the canonical style of the +document but can use the default formatting. +If the entry is already sorted, preserving the sort order is preferred. + +When removing entries, +comments on the same line should be removed but comments on following lines +should be preserved. + +Inconsistencies in style after making a change are left to the user and their +preferred auto-formatter.