Merge pull request #6 from AppDifferentia/update-document

[Doc] Update documentation

Author: weisunOW

README.md

@@ -1,2 +1,77 @@
-# danger-swift-commit-lint
-A Danger-Swift plugin to check commit messages
+# Commit Lint For Danger-Swift
+
+A [`danger-swift`]("https://github.com/danger/swift") plugin to check each commit messages on the branch. This project is inspired by [`danger-commit-lint`](https://github.com/jonallured/danger-commit_lint) and its commit linting rules are ported too.
+
+## Installation
+
+Add `DangerSwiftCommitLint` to your `Package.file`
+```Swift
+.package(url: "https://github.com/AppDifferentia/danger-swift-commit-lint", from: "0.0.1")
+```
+
+## Usage
+
+Simply add the following lines to your `Dangerfile.swift`
+
+```Swift
+import Danger
+
+let danger = Danger()
+
+//...
+
+let commitLint = DangerSwiftCommitLint(danger: danger)
+commitLint.check()
+```
+
+That will check each commit in the PR to ensure the following is true:
+
+- Commit subject begins with a capital letter (`Sources/DangerSwiftLint/CommitLint/SubjectCapitalLetter`)
+- Commit subject is more than one word (`Sources/DangerSwiftLint/CommitLint/SubjectWord`)
+- Commit subject is no longer than 50 characters (`Sources/DangerSwiftLint/CommitLint/SubjectLength`)
+- Commit subject does not end in a period (`Sources/DangerSwiftLint/CommitLint/SubjectPeriod`)
+- Commit subject and body are separated by an empty line (`Sources/DangerSwiftLint/CommitLint/BodyEmptyLine`)
+
+By default, Commit Lint fails, but you can configure this behavior.
+
+E.g.
+
+```Swift
+import Danger
+
+let danger = Danger()
+
+//...
+
+let configuration = DangerSwiftCommitLint.Configuration(warn: .all)
+let commitLint = DangerSwiftCommitLint(danger: danger, configuration: configuration)
+commitLint.check()
+```
+
+## Configuration
+
+The commit lint can be configured with following 5 parameters.
+
+- `disabled`: can be `.all` or `.selected([ ... ])`, see [`DangerSwiftCommitLint/Configuration`]("DangerSwiftCommitLint/Configuration")
+- `warn`: can be `.all` or `.selected([ ... ])`, see [`DangerSwiftCommitLint/Configuration`]("DangerSwiftCommitLint/Configuration")
+- `fail`: can be `.all` or `.selected([ ... ])`, see [`DangerSwiftCommitLint/Configuration`]("DangerSwiftCommitLint/Configuration")
+- `limit`: limits the number commits to lint. E.g. `limit: 1` will limit the commit to the oldest commit on the branch
+- `custom`: allow caller to pass an array of custom linter that conforms to `DangerSwiftCommitLint.CommitLint` protocol
+
+E.g.
+
+```Swift
+struct Configuration {
+
+    init(
+        disabled: CommitLintSelection = .selected([]),
+        warn: CommitLintSelection = .selected([]),
+        fail: CommitLintSelection = .all,
+        limit: Int = 0,
+        custom: [CommitLint.Type] = []
+    ) {
+        // ...
+    }
+
+}
+```

…itLint/CommitChecker/BodyEmptyLine.swift …ommitLint/CommitLint/BodyEmptyLine.swiftSources/DangerSwiftCommitLint/CommitChecker/BodyEmptyLine.swift renamed to Sources/DangerSwiftCommitLint/CommitLint/BodyEmptyLine.swift Sources/DangerSwiftCommitLint/CommitChecker/BodyEmptyLine.swift renamed to Sources/DangerSwiftCommitLint/CommitLint/BodyEmptyLine.swift

@@ -2,65 +2,66 @@ import Foundation
 
 public extension DangerSwiftCommitLint {
     /// All commit checkers provided by `DangerSwiftCommitLint`
-    enum CommitCheckerType: CaseIterable, Hashable {
-        /// Commit subject and body are separated by an empty line (`CommitChecker/BodyEmptyLineCheck`)
+    enum CommitLintType: CaseIterable, Hashable {
+        /// Commit subject and body are separated by an empty line (`CommitLint/BodyEmptyLineCheck`)
         case bodyEmptyLine
-        /// Commit subject begins with a capital letter (`CommitChecker/SubjectCapCheck`)
+        /// Commit subject begins with a capital letter (`CommitLint/SubjectCapCheck`)
         case subjectCapitalLetter
-        /// Commit subject is no longer than 50 characters (`CommitChecker/SubjectLengthCheck`)
+        /// Commit subject is no longer than 50 characters (`CommitLint/SubjectLengthCheck`)
         case subjectLength
-        /// Commit subject does not end in a period (`CommitChecker/SubjectPeriodCheck`)
+        /// Commit subject does not end in a period (`CommitLint/SubjectPeriodCheck`)
         case subjectPeriod
-        /// Commit subject is more than one word (`CommitChecker/SubjectWordCheck`)
+        /// Commit subject is more than one word (`CommitLint/SubjectWordCheck`)
         case subjectWord
     }
 
     /// Checker selection
-    enum CommitCheckerSelection {
+    enum CommitLintSelection {
         /// Select all checkers
         case all
         /// Select a set of checkers
-        case selected(Set<CommitCheckerType>)
+        case selected(Set<CommitLintType>)
     }
 
+    /// Configuration for `DangerSwiftCommitLint`
     struct Configuration {
         let limit: Int
 
-        private let disabled: CommitCheckerSelection
-        private let warn: CommitCheckerSelection
-        private let fail: CommitCheckerSelection
-        private let customCheckers: [CommitLint.Type]
+        private let disabled: CommitLintSelection
+        private let warn: CommitLintSelection
+        private let fail: CommitLintSelection
+        private let custom: [CommitLint.Type]
 
         /// Initialize the configuration.
         /// - Parameters:
-        ///   - disabled: The selected checks to skip.
-        ///   - warn: The selected checks to warn on.
-        ///   - fail: The selected checks to fail on.
+        ///   - disabled: The selected commit lint to skip.
+        ///   - warn: The selected commit lint to warn on.
+        ///   - fail: The selected commit lint to fail on.
         ///   - limit: The number of commits to check.
-        ///   - customCheckers: An array of custom checkers.
+        ///   - customCheckers: An array of custom checkers. This array will be added to all checkers.
         public init(
-            disabled: CommitCheckerSelection = .selected([]),
-            warn: CommitCheckerSelection = .selected([]),
-            fail: CommitCheckerSelection = .all,
+            disabled: CommitLintSelection = .selected([]),
+            warn: CommitLintSelection = .selected([]),
+            fail: CommitLintSelection = .all,
             limit: Int = 0,
-            customCheckers: [CommitLint.Type] = []
+            custom: [CommitLint.Type] = []
         ) {
             self.disabled = disabled
             self.warn = warn
             self.fail = fail
             self.limit = limit
-            self.customCheckers = customCheckers
+            self.custom = custom
         }
     }
 }
 
 extension DangerSwiftCommitLint.Configuration {
     static var defaultCheckers: [CommitLint.Type] {
-        DangerSwiftCommitLint.CommitCheckerType.allCases.map(\.type)
+        DangerSwiftCommitLint.CommitLintType.allCases.map(\.type)
     }
 
     var allCheckers: [CommitLint.Type] {
-        Self.defaultCheckers + customCheckers
+        Self.defaultCheckers + custom
     }
 
     var disabledCheckers: [CommitLint.Type] {
@@ -96,7 +97,7 @@ extension DangerSwiftCommitLint.Configuration {
     }
 }
 
-private extension DangerSwiftCommitLint.CommitCheckerType {
+private extension DangerSwiftCommitLint.CommitLintType {
     var type: CommitLint.Type {
         switch self {
         case .bodyEmptyLine: return BodyEmptyLine.self

…ommitLint/CommitChecker/CommitLint.swift …ftCommitLint/CommitLint/CommitLint.swiftSources/DangerSwiftCommitLint/CommitChecker/CommitLint.swift renamed to Sources/DangerSwiftCommitLint/CommitLint/CommitLint.swift Sources/DangerSwiftCommitLint/CommitChecker/CommitLint.swift renamed to Sources/DangerSwiftCommitLint/CommitLint/CommitLint.swift

@@ -1,6 +1,8 @@
 import Danger
 import Foundation
 
+/// A protocol for dependency inject `DangerDSL`.
+/// - `DangerSwiftCommitLint` only require these interfaces.
 public protocol DangerDSLProviding {
     var git: Git { get }
 
@@ -10,6 +12,7 @@ public protocol DangerDSLProviding {
 
 extension DangerDSL: DangerDSLProviding {}
 
+/// A Danger-Swift plugin to lint each commit in the PR. See `Configuration` for linter configuration.
 public final class DangerSwiftCommitLint {
     private enum Constants {
         static let disableAllChecksMessage = "All checks were disabled, nothing to do."
@@ -22,7 +25,7 @@ public final class DangerSwiftCommitLint {
     /// - Parameters:
     ///   - danger: An instance of `Danger.DangerDSL`.
     ///   - configuration: Linter configuration.
-    public init(danger: DangerDSLProviding = Danger(), configuration: Configuration) {
+    public init(danger: DangerDSLProviding = Danger(), configuration: Configuration = .init()) {
         self.danger = danger
         self.configuration = configuration
     }