diff --git a/Sources/BumpVersion/Documentation.docc/Articles/OptionsReference.md b/Sources/BumpVersion/Documentation.docc/Articles/OptionsReference.md index d5beded..407797e 100644 --- a/Sources/BumpVersion/Documentation.docc/Articles/OptionsReference.md +++ b/Sources/BumpVersion/Documentation.docc/Articles/OptionsReference.md @@ -19,18 +19,24 @@ of their usage. ### Configuration Options -| Short | Long | Argument | Description | -| ----- | ---------------------------------- | ----------- | ---------------------------------------------------------------------------------- | -| -f | --configuration-file | | The path to the configuration to use. | -| -m | --target-module | | The target module name inside your project | -| -n | --target-file-name | | The file name for the version to be found inside the module | -| -p | --target-file-path | | Path to a version file in your project | -| N/A | --enable-git-tag/--disable-git-tag | N/A | Use the git-tag version strategy | -| N/A | --require-exact-match | N/A | Fail if a tag is not specifically set on the commit | -| N/A | --require-existing-semvar | N/A | Fail if an existing semvar is not found in the version file. | -| -c | --custom-command | | Use a custom command strategy for the version (any options need to proceed a '--') | -| N/A | --commit-sha/--no-commit-sha | N/A | Use the commit sha with branch version or pre-release strategy | -| N/A | --require-configuration | N/A | Fail if a configuration file is not found | +| Short | Long | Argument | Description | +| ----- | ---------------------------------- | ------------ | ----------------------------------------------------------------------------------- | +| -f | --configuration-file | | The path to the configuration to use. | +| -m | --target-module | | The target module name inside your project | +| -n | --target-file-name | | The file name for the version to be found inside the module | +| -p | --target-file-path | | Path to a version file in your project | +| N/A | --enable-git-tag/--disable-git-tag | N/A | Use the git-tag version strategy | +| N/A | --require-exact-match | N/A | Fail if a tag is not specifically set on the commit | +| N/A | --require-existing-semvar | N/A | Fail if an existing semvar is not found in the version file. | +| -c | --custom-command | | Use a custom command strategy for the version (any options need to proceed a '--') | +| N/A | --commit-sha/--no-commit-sha | N/A | Use the commit sha with branch version or pre-release strategy | +| N/A | --require-configuration | N/A | Fail if a configuration file is not found | +| N/A | --precedence | | The precedence for when a file exists (values: ['file', 'strategy'], default: file) | + +> Note: Precedence is used as tie breaker if the version in the file does not agree with the version +> from the configured strategy. This can happen if a file was edited / bumped manually or the value +> returned from the external command is not similar to the version in the file. By default the file +> will take precedence over what is returned from the strategy. #### Pre-Release Options diff --git a/Sources/ConfigurationClient/Configuration.swift b/Sources/ConfigurationClient/Configuration.swift index abb86a0..217745f 100644 --- a/Sources/ConfigurationClient/Configuration.swift +++ b/Sources/ConfigurationClient/Configuration.swift @@ -257,8 +257,15 @@ public extension Configuration { /// struct SemVar: Codable, Equatable, Sendable { + /// Allow semvar to include a pre-release suffix. public let allowPreRelease: Bool? + /// Set the precedence of version loaded from file versus + /// the version returned by the strategy. + /// + /// These can not always agree / reflect the same version, + /// so the default is to give the file version precedence over + /// the strategy. public let precedence: Precedence? /// Optional pre-releas suffix strategy. @@ -270,11 +277,12 @@ public extension Configuration { /// Fail if an existing semvar is not parsed from the file or version generation strategy. public let requireExistingSemVar: Bool? + /// The strategy used to derive a version for the project. public let strategy: Strategy? public init( allowPreRelease: Bool? = true, - precedence: Precedence? = .default, + precedence: Precedence? = nil, preRelease: PreRelease? = nil, requireExistingFile: Bool? = false, requireExistingSemVar: Bool? = false, @@ -288,15 +296,31 @@ public extension Configuration { self.strategy = strategy } + /// Represents a strategy to derive a version for a project. public enum Strategy: Codable, Equatable, Sendable { + /// A custom external command that should return a string that + /// can be parsed as a semvar. case command(arguments: [String]) + + /// Use `git describe --tags` optionally as an exact match. case gitTag(exactMatch: Bool? = false) } + /// Represents the precedence for which version to use when a file + /// exists, as they don't always agree. For example, a file could be edited + /// manually or the tag doesn't represent what is parsed from calling the + /// strategy. + /// + /// The default is to defer to the file (if it exists) as having precedence over + /// the strategy. public enum Precedence: String, CaseIterable, Codable, Equatable, Sendable { + + /// Give the file precedence over the strategy. case file + /// Give the strategy precedence over the file. case strategy + /// The default precedence. public static var `default`: Self { .file } }