Merge branch 'docs/suggest-filling-enum-gaps' into 'master'

Recommend to fill gaps in enum values

See merge request gitlab-org/gitlab!58759

doc/development/creating_enums.md

@@ -114,3 +114,41 @@ class Pipeline < ApplicationRecord
   }
 end
 ```
+
+## Add new values in the gap
+
+After merging some EE and FOSS enums, there might be a gap between the two groups of values:
+
+```ruby
+module Enums
+  module Ci
+    module CommitStatus
+      def self.failure_reasons
+        {
+          # ...
+          data_integrity_failure: 12,
+          forward_deployment_failure: 13,
+          insufficient_bridge_permissions: 1_001,
+          downstream_bridge_project_not_found: 1_002,
+          # ...
+        }
+      end
+    end
+  end
+end
+```
+
+To add new values, you should fill the gap first.
+In the example above add `14` instead of `1_003`:
+
+```ruby
+{
+  # ...
+  data_integrity_failure: 12,
+  forward_deployment_failure: 13,
+  a_new_value: 14,
+  insufficient_bridge_permissions: 1_001,
+  downstream_bridge_project_not_found: 1_002,
+  # ...
+}
+```