[docs] add minor branding guidelines to CONTRIBUTING.md

CONTRIBUTING.md

@@ -66,6 +66,29 @@ One of the best ways we can keep _fastlane_ an approachable, stable, and dependa
 
 Help us keep _fastlane_ open and inclusive. Please read and follow our [Code of Conduct][code of conduct].
 
+## Branding
+
+We have a few guidelines for how to refer to _fastlane_ and its tools:
+
+- _fastlane_ and its actions should be written in all lowercase, even at the beginning of a sentence:
+    - ❌ "Use Fastlane to automate your screenshots."
+    - ❌ "Use _Fastlane_ to automate your screenshots."
+    - ❌ "Fastlane helps you deliver faster."
+    - ❌ "Match makes code signing management easy."
+    - ✅ "Use _fastlane_ to automate your screenshots."
+    - ✅ "_fastlane_ helps you deliver faster."
+    - ✅ "_match_ makes code signing management easy."
+- _fastlane_ and all of its actions should be italicized when written in prose:
+    - ❌ "`fastlane` is an all-in-one tool for app automation."
+    - ❌ "**fastlane** is an all-in-one tool for app automation."
+    - ❌ "fastlane is an all-in-one tool for app automation."
+    - ❌ "<ins>fastlane</ins> is an all-in-one tool for app automation."
+    - ❌ "`match` makes code signing management easy."
+    - ✅ "_fastlane_ is an all-in-one tool for app automation."
+    - ✅ "_match_ makes code signing management easy."
+
+Please use these guidelines when writing about _fastlane_ and its tools, be it when contributing to the project or writing about it elsewhere.
+
 ## Above All, Thanks for Your Contributions
 
 Thank you for reading to the end, and for taking the time to contribute to the project! If you include the 🔑 emoji at the top of the body of your issue or pull request, we'll know that you've given this your full attention and are doing your best to help!

RespondingToIssuesAndPullRequests.md

@@ -1,6 +1,6 @@
 # How to respond to Issues and PRs
 
-## How we treat each other  
+## How we treat each other
 
 When replying to issues and PRs, make sure you always follow our [Code of Conduct](CODE_OF_CONDUCT.md) and our [vision for fastlane](VISION.md). Make sure to read these thoroughly and understand them before you interact with any other users! In general, be nice to each other, and treat **everyone** with the same respect and dignity.
 

fastlane/Fastfile

@@ -584,21 +584,15 @@ end
 
 desc "Ensure the correct formatting for the fastlane tools"
 private_lane :ensure_tool_name_formatting do
+  test_tool_name_formatting_ensurance_lane
   UI.message("🕗  Verifying tool name formatting...")
   require 'fastlane/tools'
   errors = []
   Dir.chdir("..") do
     Dir["**/*.md"].each do |path|
       content = File.read(path)
-      Fastlane::TOOLS.each do |tool|
-        errors << "Use _#{tool}_ instead of `#{tool}` to mention a tool in the docs in '#{path}'" if content.include?("`#{tool}`")
-        errors << "Use _#{tool}_ instead of `_#{tool}_` to mention a tool in the docs in '#{path}'" if content.include?("`_#{tool}_`")
-        errors << "Use [_#{tool}_] instead of [#{tool}] to mention a tool in the docs in '#{path}'" if content.include?("[#{tool}]")
-        errors << "Use <em>#{tool}<em> instead of <code>#{tool}</code> to mention a tool in the docs in '#{path}'" if content.include?("<code>#{tool}</code>")
-        if content.include?("_#{tool.to_s.capitalize}_") || content.include?("`#{tool.to_s.capitalize}`")
-          errors << "fastlane tools have to be formatted in lower case: #{tool} in '#{path}'"
-        end
-      end
+      helper = Helper::ToolNameFormattingHelper.new(content: content, path: path)
+      errors += helper.find_tool_name_formatting_errors
     end
   end
   errors.each { |a| UI.error(a) }

fastlane/helper/tool_name_formatting_helper.rb

@@ -0,0 +1,38 @@
+module Fastlane
+  module Helper
+    class ToolNameFormattingHelper
+      attr_accessor :content, :path
+
+      def initialize(content:, path:)
+        @content = content
+        @path = path
+      end
+
+      def find_tool_name_formatting_errors
+        errors = []
+        Fastlane::TOOLS.each do |tool|
+          lines = content.split("\n")
+          lines.each_with_index do |line, index|
+            line_number = index + 1
+            # Ignore checks if line starts with "^\s*- ❌" (i.e. if it's a line that's already been marked as incorrect)
+            # and if the file is CONTRIBUTING.md (i.e. if it's the branding guidelines section)
+            next if line =~ /^\s*- ❌/ && path == "CONTRIBUTING.md"
+            errors << "Use _#{tool}_ instead of `#{tool}` to mention a tool in the docs in '#{path}:#{line_number}': #{line}" if line.include?("`#{tool}`")
+            errors << "Use _#{tool}_ instead of `_#{tool}_` to mention a tool in the docs in '#{path}:#{line_number}': #{line}" if line.include?("`_#{tool}_`")
+            errors << "Use [_#{tool}_] instead of [#{tool}] to mention a tool in the docs in '#{path}:#{line_number}': #{line}" if line.include?("[#{tool}]")
+            errors << "Use _#{tool}_ instead of **#{tool}** to mention a tool in the docs in '#{path}:#{line_number}': #{line}" if line.include?("**#{tool}**")
+            errors << "Use <em>#{tool}<em> instead of <code>#{tool}</code> to mention a tool in the docs in '#{path}:#{line_number}': #{line}" if line.include?("<code>#{tool}</code>")
+            errors << "Use <em>#{tool}<em> or _#{tool}_ instead of <ins>#{tool}</ins> to mention a tool in the docs in '#{path}:#{line_number}': #{line}" if line.include?("<ins>#{tool}</ins>")
+
+            line.scan(/([A-Z_]*)([_ `"])(#{Regexp.escape(tool.to_s)})\2([A-Z_]*)/i) do |prefix, delimiter, tool_name, suffix|
+              wrong_case = tool_name != tool.to_s.downcase
+              looks_like_an_env_var = (tool_name == tool_name.upcase) && delimiter == '_' && (!prefix.empty? || !suffix.empty?)
+              errors << "fastlane tools have to be formatted in lowercase: #{tool} in '#{path}:#{line_number}': #{line}" if !looks_like_an_env_var && wrong_case
+            end
+          end
+        end
+        errors
+      end
+    end
+  end
+end

fastlane/lib/fastlane/actions/docs/build_app.md

@@ -42,7 +42,7 @@ fastlane gym
 
 _gym_ uses the latest APIs to build and sign your application which results in much faster build times.
 
-|          |  Gym Features  |
+|          |     _gym_      |
 |----------|----------------|
 🚀 | _gym_ builds 30% faster than other build tools like [shenzhen](https://github.com/nomad/shenzhen)
 🏁 | Beautiful inline build output

fastlane/lib/fastlane/actions/docs/capture_android_screenshots.md

@@ -32,7 +32,7 @@ androidTestImplementation 'tools.fastlane:screengrab:x.x.x'
 
 The latest version is [ ![Download](https://maven-badges.herokuapp.com/maven-central/tools.fastlane/screengrab/badge.svg)](https://search.maven.org/artifact/tools.fastlane/screengrab)
 
-As of Screengrab version 2.0.0, all Android test dependencies are AndroidX dependencies. This means a device with API 18+, Android 4.3 or greater is required. If you wish to capture screenshots with an older Android OS, then you must use a 1.x.x version.
+As of _screengrab_ version 2.0.0, all Android test dependencies are AndroidX dependencies. This means a device with API 18+, Android 4.3 or greater is required. If you wish to capture screenshots with an older Android OS, then you must use a 1.x.x version.
 
 ##### Configuring your Manifest Permissions
 
@@ -63,21 +63,21 @@ Ensure that the following permissions exist in your **src/debug/AndroidManifest.
 1. Add `LocaleTestRule` to your tests class to handle automatic switching of locales.
 
    If you're using Java use:
-   
+
    ```java
    @ClassRule
    public static final LocaleTestRule localeTestRule = new LocaleTestRule();
    ```
-   
+
    If you're using Kotlin use:
-   
+
    ```kotlin
    @Rule @JvmField
    val localeTestRule = LocaleTestRule()
    ```
-   
+
    The `@JvmField` annotation is important. It won't work like this:
-   
+
    ```kotlin
    companion object {
        @get:ClassRule

fastlane/lib/fastlane/actions/docs/get_push_certificate.md

@@ -48,7 +48,7 @@ This does the following:
 - Downloads the certificate
 - Generates a new ```.pem``` file in the current working directory, which you can upload to your server
 
-Note that _pem_ will never revoke your existing certificates. _pem_ can't download any of your existing push certificates, as the private key is only available on the machine it was created on. 
+Note that _pem_ will never revoke your existing certificates. _pem_ can't download any of your existing push certificates, as the private key is only available on the machine it was created on.
 
 If you already have a push certificate enabled, which is active for at least 30 more days, _pem_ will not create a new certificate. If you still want to create one, use the `force`:
 
@@ -111,7 +111,7 @@ If you need the `p12` in your keychain, perhaps to test push with an app like [K
 Enter Import Password:
   <hit enter: the p12 has no password>
 MAC verified OK
-Enter PEM pass phrase:
+Enter your pem passphrase:
   <enter a temporary password to encrypt the pem file>
 
 % openssl pkcs12 -export -in my.pem -out my-with-passphrase.p12

fastlane/lib/fastlane/new_action.rb

@@ -7,7 +7,7 @@ def self.run(new_action_name: nil)
     end
 
     def self.fetch_name
-      puts("Must be lower case, and use a '_' between words. Do not use '.'".green)
+      puts("Must be lowercase, and use a '_' between words. Do not use '.'".green)
       puts("examples: 'testflight', 'upload_to_s3'".green)
       name = UI.input("Name of your action: ")
       until name_valid?(name)

fastlane/lib/fastlane/plugins/plugin_info_collector.rb

@@ -45,7 +45,7 @@ def collect_plugin_name(initial_name = nil)
           @ui.message("\nThe gem name '#{gem_name}' is already taken on RubyGems, please choose a different plugin name.")
         else
           # That's a naming error
-          @ui.message("\nPlugin names can only contain lower case letters, numbers, and underscores")
+          @ui.message("\nPlugin names can only contain lowercase letters, numbers, and underscores")
           @ui.message("and should not contain 'fastlane' or 'plugin'.")
         end
       end
@@ -54,7 +54,7 @@ def collect_plugin_name(initial_name = nil)
     end
 
     def plugin_name_valid?(name)
-      # Only lower case letters, numbers and underscores allowed
+      # Only lowercase letters, numbers and underscores allowed
       /^[a-z0-9_]+$/ =~ name &&
         # Does not contain the words 'fastlane' or 'plugin' since those will become
         # part of the gem name
@@ -79,7 +79,7 @@ def fix_plugin_name(name)
       name = name.to_s.downcase
       fixes = {
         /[\- ]/ => '_', # dashes and spaces become underscores
-        /[^a-z0-9_]/ => '', # anything other than lower case letters, numbers and underscores is removed
+        /[^a-z0-9_]/ => '', # anything other than lowercase letters, numbers and underscores is removed
         /fastlane[_]?/ => '', # 'fastlane' or 'fastlane_' is removed
         /plugin[_]?/ => '' # 'plugin' or 'plugin_' is removed
       }

fastlane/spec/fixtures/fastfiles/tool_name_formatting.txt

@@ -0,0 +1,27 @@
+Some lines in this file should start with a special formatting (the same used in CONTRIBUTING.md), so they are ignored by the name formatting checks. For every line, however, the emoji that the line ends will tell whether the respective line should pass the check or not (just for a visual reference of the reader).
+
+- ❌ "Use Fastlane to automate your screenshots." ✅
+- ❌ "Use _Fastlane_ to automate your screenshots." ✅
+- ❌ "Fastlane helps you deliver faster." ✅
+- ❌ "Match makes code signing management easy." ✅
+Use _fastlane_ to automate your screenshots. ✅
+_fastlane_ helps you deliver faster. ✅
+_match_ makes code signing management easy. ✅
+- ❌ "`fastlane` is an all-in-one tool for app automation." ✅
+- ❌ "**fastlane** is an all-in-one tool for app automation." ✅
+- ❌ "fastlane is an all-in-one tool for app automation." ✅
+- ❌ "<ins>fastlane</ins> is an all-in-one tool for app automation." ✅
+- ❌ "`match` makes code signing management easy." ✅
+_fastlane_ is an all-in-one tool for app automation. ✅
+_match_ makes code signing management easy. ✅
+FastLane makes code signing management easy. Unfortunately we can't catch this brand misalignment because there's no delimiter around the keyword. ✅
+Fastlane makes code signing management easy. Unfortunately we can't catch this brand misalignment because there's no delimiter around the keyword. ✅
+_FastLane_ makes code signing management easy. ❌
+A sentence that has a tool name in the beginning of an env var: `MATCH_FILE` ✅
+A sentence that has a tool name in the end of an env var: `UPDATE_FASTLANE` ✅
+A sentence that has a tool name in the middle of an env var: `SOMETHING_FASTLANE_SOMETHING` ✅
+A sentence that contains a _FastLane_ keyword, but also an env var: `FASTLANE_SKIP_CHANGELOG`. ❌
+A sentence that contains `<PATH_TO_YOUR_LOCAL_FASTLANE_CLONE>` placeholder env var. ✅
+A sentence that contains `File.expand_path("<PATH_TO_YOUR_LOCAL_FASTLANE_CLONE>")` placeholder string. ✅
+A sentence that has a weird-looking env var with no prefix other than the delimiter: `_FASTLANE_SOMETHING` ✅
+A sentence that has a weird-looking env var with no suffix other than the delimiter: `SOMETHING_FASTLANE_` ✅

fastlane/spec/helper/tool_name_formatting_helper_spec.rb

@@ -0,0 +1,18 @@
+require_relative '../../helper/tool_name_formatting_helper.rb'
+
+describe Fastlane::Helper::ToolNameFormattingHelper do
+  before(:each) do
+    content = File.read("fastlane/spec/fixtures/fastfiles/tool_name_formatting.txt")
+    @helper = Fastlane::Helper::ToolNameFormattingHelper.new(content: content, path: "CONTRIBUTING.md")
+  end
+
+  describe "when parsing fixture file" do
+    it "should match array of expected errors" do
+      expected_errors = [
+        "fastlane tools have to be formatted in lowercase: fastlane in 'CONTRIBUTING.md:19': _FastLane_ makes code signing management easy. ❌",
+        "fastlane tools have to be formatted in lowercase: fastlane in 'CONTRIBUTING.md:23': A sentence that contains a _FastLane_ keyword, but also an env var: `FASTLANE_SKIP_CHANGELOG`. ❌"
+      ]
+      expect(@helper.find_tool_name_formatting_errors).to match_array(expected_errors)
+    end
+  end
+end

spaceship/docs/Architecture.md

@@ -1,4 +1,4 @@
-# Spaceship Architecture
+# _spaceship_ Architecture
 
 _spaceship_ uses [Faraday](https://github.com/lostisland/faraday) to interact with multiple Apple API endpoints:
 

spaceship/docs/DeveloperPortal.md

@@ -359,7 +359,7 @@ profiles = Spaceship::Portal.provisioning_profile.in_house.all
 
 ### Multiple Spaceships
 
-Sometimes one _spaceship_ just isn't enough. That's why this library has its own Spaceship Launcher to launch and use multiple _spaceships_ at the same time :rocket:
+Sometimes one _spaceship_ just isn't enough. That's why this library has its own _spaceship_ launcher to launch and use multiple _spaceships_ at the same time :rocket:
 
 ```ruby
 # Launch 2 spaceships

spaceship/docs/README.md

@@ -1,4 +1,4 @@
-# Spaceship Documentation
+# _spaceship_ Documentation
 
 ## API