149 lines
4 KiB
Ruby
149 lines
4 KiB
Ruby
# frozen_string_literal: true
|
|
|
|
module Gitlab
|
|
module Graphql
|
|
class Deprecation
|
|
REASON_RENAMED = :renamed
|
|
REASON_ALPHA = :alpha
|
|
|
|
REASONS = {
|
|
REASON_RENAMED => 'This was renamed.',
|
|
REASON_ALPHA => 'This feature is in Alpha. It can be changed or removed at any time.'
|
|
}.freeze
|
|
|
|
include ActiveModel::Validations
|
|
|
|
validates :milestone, presence: true, format: { with: /\A\d+\.\d+\z/, message: 'must be milestone-ish' }
|
|
validates :reason, presence: true
|
|
validates :reason,
|
|
format: { with: /.*[^.]\z/, message: 'must not end with a period' },
|
|
if: :reason_is_string?
|
|
validate :milestone_is_string
|
|
validate :reason_known_or_string
|
|
|
|
def self.parse(alpha: nil, deprecated: nil)
|
|
options = alpha || deprecated
|
|
return unless options
|
|
|
|
if alpha
|
|
raise ArgumentError, '`alpha` and `deprecated` arguments cannot be passed at the same time' \
|
|
if deprecated
|
|
|
|
options[:reason] = :alpha
|
|
end
|
|
|
|
new(**options)
|
|
end
|
|
|
|
def initialize(reason: nil, milestone: nil, replacement: nil)
|
|
@reason = reason.presence
|
|
@milestone = milestone.presence
|
|
@replacement = replacement.presence
|
|
end
|
|
|
|
def ==(other)
|
|
return false unless other.is_a?(self.class)
|
|
|
|
[reason_text, milestone, replacement] == [:reason_text, :milestone, :replacement].map do |attr|
|
|
other.send(attr) # rubocop: disable GitlabSecurity/PublicSend
|
|
end
|
|
end
|
|
alias_method :eql, :==
|
|
|
|
def markdown(context: :inline)
|
|
parts = [
|
|
"#{changed_in_milestone(format: :markdown)}.",
|
|
reason_text,
|
|
replacement_markdown.then { |r| "Use: #{r}." if r }
|
|
].compact
|
|
|
|
case context
|
|
when :block
|
|
['WARNING:', *parts].join("\n")
|
|
when :inline
|
|
parts.join(' ')
|
|
end
|
|
end
|
|
|
|
def replacement_markdown
|
|
return unless replacement.present?
|
|
return "`#{replacement}`" unless replacement.include?('.') # only fully qualified references can be linked
|
|
|
|
"[`#{replacement}`](##{replacement.downcase.tr('.', '')})"
|
|
end
|
|
|
|
def edit_description(original_description)
|
|
@original_description = original_description
|
|
return unless original_description
|
|
|
|
original_description + description_suffix
|
|
end
|
|
|
|
def original_description
|
|
return unless @original_description
|
|
return @original_description if @original_description.ends_with?('.')
|
|
|
|
"#{@original_description}."
|
|
end
|
|
|
|
def deprecation_reason
|
|
[
|
|
reason_text,
|
|
replacement && "Please use `#{replacement}`.",
|
|
"#{changed_in_milestone}."
|
|
].compact.join(' ')
|
|
end
|
|
|
|
def alpha?
|
|
reason == REASON_ALPHA
|
|
end
|
|
|
|
private
|
|
|
|
attr_reader :reason, :milestone, :replacement
|
|
|
|
def milestone_is_string
|
|
return if milestone.is_a?(String)
|
|
|
|
errors.add(:milestone, 'must be a string')
|
|
end
|
|
|
|
def reason_known_or_string
|
|
return if REASONS.key?(reason)
|
|
return if reason_is_string?
|
|
|
|
errors.add(:reason, 'must be a known reason or a string')
|
|
end
|
|
|
|
def reason_is_string?
|
|
reason.is_a?(String)
|
|
end
|
|
|
|
def reason_text
|
|
@reason_text ||= REASONS[reason] || "#{reason.to_s.strip}."
|
|
end
|
|
|
|
def description_suffix
|
|
" #{changed_in_milestone}: #{reason_text}"
|
|
end
|
|
|
|
# Returns 'Deprecated in <milestone>' for proper deprecations.
|
|
# Retruns 'Introduced in <milestone>' for :alpha deprecations.
|
|
# Formatted to markdown or plain format.
|
|
def changed_in_milestone(format: :plain)
|
|
verb = if alpha?
|
|
'Introduced'
|
|
else
|
|
'Deprecated'
|
|
end
|
|
|
|
case format
|
|
when :plain
|
|
"#{verb} in #{milestone}"
|
|
when :markdown
|
|
"**#{verb}** in #{milestone}"
|
|
end
|
|
end
|
|
end
|
|
end
|
|
end
|