docs: update linters documentation to include conflictingmarkers linter details

Author: yongruilin

docs/linters.md

@@ -2,6 +2,7 @@
 
 - [Conditions](#conditions) - Checks that `Conditions` fields are correctly formatted
 - [CommentStart](#commentstart) - Ensures comments start with the serialized form of the type
+- [ConflictingMarkers](#conflictingmarkers) - Detects mutually exclusive markers on the same field
 - [DuplicateMarkers](#duplicatemarkers) - Checks for exact duplicates of markers
 - [Integers](#integers) - Validates usage of supported integer types
 - [JSONTags](#jsontags) - Ensures proper JSON tag formatting
@@ -73,6 +74,60 @@ The `commentstart` linter can automatically fix comments that do not start with
 
 When the `json` tag is present, and matches the first word of the field comment in all but casing, the linter will suggest that the comment be updated to match the `json` tag.
 
+## ConflictingMarkers
+
+The `conflictingmarkers` linter detects and reports when mutually exclusive markers are used on the same field.
+This prevents common configuration errors and unexpected behavior in Kubernetes API types.
+
+The linter reports issues when markers from both sets of a conflict pair are present on the same field.
+It does NOT report issues when multiple markers from the same set are present - only when markers from
+different sets within the same conflict definition are found together.
+
+The linter is configurable and allows users to define sets of conflicting markers.
+Each conflict set must specify:
+- A unique name for the conflict
+- Two sets of markers that are mutually exclusive
+- A description explaining why the markers conflict
+
+### Configuration
+
+```yaml
+lintersConfig:
+  conflictingmarkers:
+    conflicts:
+      - name: "optional_vs_required"
+        setA: 
+          - "optional"
+          - "+kubebuilder:validation:Optional"
+          - "+k8s:validation:optional"
+        setB:
+          - "required"
+          - "+kubebuilder:validation:Required"
+          - "+k8s:validation:required"
+        description: "A field cannot be both optional and required"
+      - name: "default_vs_required"
+        setA:
+          - "default"
+          - "+kubebuilder:default"
+        setB:
+          - "required"
+          - "+kubebuilder:validation:Required"
+          - "+k8s:validation:required"
+        description: "A field with a default value cannot be required"
+      - name: "my_custom_conflict"
+        setA: 
+          - "custom:marker1"
+          - "custom:marker2"
+        setB:
+          - "custom:marker3"
+          - "custom:marker4"
+        description: "These markers conflict because..."
+```
+
+**Note**: This linter is not enabled by default and must be explicitly enabled in the configuration.
+
+The linter does not provide automatic fixes as it cannot determine which conflicting marker should be removed.
+
 ## DuplicateMarkers
 
 The duplicatemarkers linter checks for exact duplicates of markers for types and fields.