[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,14 @@ end
 
 desc "Ensure the correct formatting for the fastlane tools"
 private_lane :ensure_tool_name_formatting do
+  require_relative "../fastlane/helper/tool_name_formatting_helper.rb"
   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(path: path, is_documenting_invalid_examples: path == 'CONTRIBUTING.md')
+      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,44 @@
+module Fastlane
+  module Helper
+    class ToolNameFormattingHelper
+      attr_accessor :path, :is_documenting_invalid_examples
+
+      # @param [String] path Path to the file to be checked for tool formatting
+      # @param [Bool] is_documenting_invalid_examples
+      #        Ignore checks if line starts with "^\s*- ❌" (i.e. if it's a line that's already been marked as incorrect)
+      #        Typically used for files like `CONTRIBUTING.md`` (i.e. if it's the branding guidelines section)
+      #
+      def initialize(path:, is_documenting_invalid_examples: false)
+        @path = path
+        @is_documenting_invalid_examples = is_documenting_invalid_examples
+      end
+
+      def find_tool_name_formatting_errors
+        errors = []
+        File.readlines(path, mode: 'rb:BOM|UTF-8').each_with_index do |line, index|
+          line_number = index + 1
+          line.chomp! # Remove \n at end of line, to avoid including it in the error messages
+          Fastlane::TOOLS.each do |tool|
+            next if is_documenting_invalid_examples && line =~ /^\s*- ❌/
+
+            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|
+              is_lowercase = tool_name == tool.to_s.downcase
+              looks_like_an_env_var = (tool_name == tool_name.upcase) && delimiter == '_' && (!prefix.empty? || !suffix.empty?)
+              looks_like_ruby_module = line == "module #{tool_name}"
+              is_valid_case = is_lowercase || looks_like_an_env_var || looks_like_ruby_module
+              errors << "fastlane tools have to be formatted in lowercase: #{tool} in '#{path}:#{line_number}': #{line}" unless is_valid_case
+            end
+          end
+        end
+        errors
+      end
+    end
+  end
+end

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

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

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
@@ -87,7 +87,7 @@ Ensure that the following permissions exist in your **src/debug/AndroidManifest.
 
 2. To capture screenshots, add the following to your tests `Screengrab.screenshot("name_of_screenshot_here");` on the appropriate screens
 
-# Generating Screenshots with Screengrab
+# Generating Screenshots with _screengrab_
 - Then, before running `fastlane screengrab` you'll need a debug and test apk
   - You can create your APKs manually with `./gradlew assembleDebug assembleAndroidTest`
   - You can also create a lane and use `build_android_app`:
@@ -228,7 +228,7 @@ When using JUnit 3 you'll need to add a bit more code:
 
 ## Clean Status Bar
 
-Screengrab can clean your status bar to make your screenshots even more beautiful.
+_screengrab_ can clean your status bar to make your screenshots even more beautiful.
 It is simply a wrapper that allows configuring SystemUI DemoMode in your code.
 Note: the clean status bar feature is only supported on devices with *API level >= 23*.
 

fastlane/lib/fastlane/actions/docs/check_app_store_metadata.md

@@ -2,7 +2,7 @@
   <img src="/img/actions/precheck.png" width="250">
 </p>
 
-Precheck
+_precheck_
 ============
 
 ###### Check your app using a community driven set of App Store review rules to avoid being rejected
@@ -23,8 +23,8 @@ Apple rejects builds for many avoidable metadata issues like including swear wor
 # Features
 
 
-|          |  precheck Features  |
-|----------|-----------------|
+|          |  _precheck_ Features  |
+|----------|-----------------------|
 🐛 |  product bug mentions
 🙅 | Swear word checker
 🤖 | Mentioning other platforms

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/actions/docs/sync_code_signing.md

@@ -408,7 +408,7 @@ fastlane match adhoc --force_for_new_devices
 
 ##### Templates (aka: custom entitlements)
 
-Match can generate profiles that contain custom entitlements by passing in the entitlement's name with the `template_name` parameter.
+_match_ can generate profiles that contain custom entitlements by passing in the entitlement's name with the `template_name` parameter.
 
 ```
 match(type: "development",

fastlane/lib/fastlane/actions/docs/upload_to_testflight.md

@@ -4,7 +4,7 @@
 
 ###### The best way to manage your TestFlight testers and builds from your terminal
 
-Pilot makes it easier to manage your app on Apple’s TestFlight. You can:
+_pilot_ makes it easier to manage your app on Apple’s TestFlight. You can:
 
 - Upload & distribute builds
 - Add & remove testers

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.
+
+- ❌ "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.
+Fastlane makes code signing management easy.
+_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,20 @@
+require_relative '../../helper/tool_name_formatting_helper.rb'
+
+describe Fastlane::Helper::ToolNameFormattingHelper do
+  let(:fixture_path) { 'fastlane/spec/fixtures/fastfiles/tool_name_formatting.txt' }
+  before(:each) do
+    @helper = Fastlane::Helper::ToolNameFormattingHelper.new(path: fixture_path, is_documenting_invalid_examples: true)
+  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 '#{fixture_path}:17': FastLane makes code signing management easy.",
+        "fastlane tools have to be formatted in lowercase: fastlane in '#{fixture_path}:18': Fastlane makes code signing management easy.",
+        "fastlane tools have to be formatted in lowercase: fastlane in '#{fixture_path}:19': _FastLane_ makes code signing management easy.",
+        "fastlane tools have to be formatted in lowercase: fastlane in '#{fixture_path}: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,10 +1,10 @@
-# Spaceship Architecture
+# _spaceship_ Architecture
 
 _spaceship_ uses [Faraday](https://github.com/lostisland/faraday) to interact with multiple Apple API endpoints:
 
 ## Overview
 
-Spaceship wraps various APIs using the following pattern:
+_spaceship_ wraps various APIs using the following pattern:
 
 A simple `client` and various data models, usually subclassed from a `Base` model (e.g. Spaceship::TestFlight::Base)
 The `client` is responsible for making HTTP requests for a given API or domain. It should be very simple and have no logic.

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