[Inclusive Language][Comments][Documentation] migrate "sanity" checks to "soundness" checks

[vanvoorden]

Background

From the Swift Code of Conduct¹:

Examples of behavior that contributes to creating a positive environment include […] [u]sing welcoming and inclusive language (e.g., prefer non-gendered words like “folks” to “guys”, non-ableist words like “soundness check” to “sanity check”, etc.)

Our Swift repo still contains legacy and "deprecated" language in many places. Let's migrate those to something more inclusive! We can start with migrating "sanity checks" to "soundness checks". We already have some examples for a head start.²³ Let's keep this moving forward and build off this previous work.

Searching through the repo, we see three main categories of changes:

• Comments and Documentation
• Constant Strings
• Symbols

Ranking from "least" to "most" risky to land without causing any bugs or unintended consequences, let's start here with migrating comments and documentation.

Changes

Here are our migrations:

• sanity to soundness
• sane to sound
• insane to unsound
• sanely to soundly

Test Plan

https://gist.github.com/vanvoorden/e46bcfd2ac6eb8eb37cf64165b8624ac

--- Build Script Analyzer ---
Build Script Log: /Users/rick/Developer/swift-project/build/.build_script_log
Build Percentage 	 Build Duration (sec) 	 Build Phase
================ 	 ==================== 	 ===========
70.6%             	 534.62                	 macosx-arm64-swift-build
19.2%             	 145.13                	 Building llvm
9.4%              	 71.5                  	 Building earlyswiftdriver
0.8%              	 5.76                  	 Building cmark
0.0%              	 0.06                  	 macosx-arm64-swift-test
0.0%              	 0.05                  	 macosx-arm64-swift-install
0.0%              	 0.04                  	 merged-hosts-lipo-core
0.0%              	 0.04                  	 macosx-arm64-extractsymbols
0.0%              	 0.04                  	 macosx-arm64-package
0.0%              	 0.04                  	 merged-hosts-lipo
Total Duration: 757.28 seconds (12m 37s)

I built swift from these changes locally and saw no errors.

Open Questions

A few Swift test files seem to contain comments that look like they might be mapping to symbols:

https://github.com/apple/swift/blob/main/test/DebugInfo/test-foundation.swift

// SANITY-DAG: !DISubprogram(name: "blah",{{.*}} line: [[@LINE+2]],{{.*}} DISPFlagDefinition

https://github.com/apple/swift/blob/main/test/SILOptimizer/access_marker_verify.swift

// call _sanityCheck(_:_:file:line:)

https://github.com/apple/swift/blob/main/test/SourceKit/CursorInfo/cursor_usr.swift

// RUN: %FileCheck %s -check-prefix=CHECK_SANITY1 < %t.from_offset.txt
// RUN: %FileCheck %s -check-prefix=CHECK_SANITY1 < %t.from_usr.txt

Does anyone have more context about these? Are these actually lowkey "symbols" that are defined or referenced somewhere else?

Next Steps

In future diffs, we can begin to migrate the remaining examples of noninclusive language (constant strings and symbols).

Acknowledgments

Thank you to @twostraws, @amartini51, and @Serena748 for beginning this important work!

Footnotes

1. https://www.swift.org/code-of-conduct/ ↩

2. https://github.com/apple/swift/pull/34667 ↩

3. https://github.com/apple/swift/pull/68993 ↩

[phausler]

@swift-ci please test

[phausler]

The changes listed seem to be mechanical and only applicable to comments. Seems good to me.

[hborla]

Thank you for this contribution! About the open questions:

// SANITY-DAG: !DISubprogram(name: "blah",{{.*}} line: [[@LINE+2]],{{.*}} DISPFlagDefinition

I'm not sure where this check prefix comes from.

// call _sanityCheck(_:_:file:line:)

This looks like just a comment that can be removed.

// RUN: %FileCheck %s -check-prefix=CHECK_SANITY1 < %t.from_offset.txt
// RUN: %FileCheck %s -check-prefix=CHECK_SANITY1 < %t.from_usr.txt

These run lines are specifying the prefix to use in the test. These can be changed as long as all of the // CHECK_SANITY1: comments are also changed to use the new prefix!

[vanvoorden]

https://ci.swift.org/job/swift-PR-macos/13233/consoleText

warning: the following paths have collided (e.g. case-sensitive paths
on a case-insensitive filesystem) and only one from the same
colliding group is in the working tree:

  'flang/test/Preprocessing/pp133.F90'
  'flang/test/Preprocessing/pp133.f90'

@phausler Hmm… it looks like llvm/llvm-project#79531 might be the reason that test build failed… would a new test run pick up that latest change from llvm?

[ktoso]

Changes all look safe/correct, thank you

[vanvoorden]

Thank you for this contribution! About the open questions:

@hborla Hmm… this diff already has some approvals on it… maybe I can try those changes in an independent diff for us to look at and test separately? Thanks!

[vanvoorden]

@swift-ci please test macOS platform

[hborla]

@swift-ci please test macOS platform

[vanvoorden]

@phausler @ktoso @mikeash Thanks for reviewing and approving! Do you think we are safe to land these changes now… or is it better to wait for every reviewer that got tagged and added here?

[mikeash]

I think you can go ahead and press the button. We can be pretty confident that this change won't break anything!

[vanvoorden]

I think you can go ahead and press the button.

I don't have an option to land AFAIK… does anyone with permission want to merge for me?

[glessard]

@vanvoorden merged. Thanks!