You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by pk...@apache.org on 2026/06/20 20:08:58 UTC

(commons-xml) 03/50: feat: add `AGENTS.md` for basic coding rules

This is an automated email from the ASF dual-hosted git repository.

ppkarwasz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/commons-xml.git

commit 73fa4275601d6411e98b01268d0598a5c0656be0
Author: Piotr P. Karwasz <pk...@apache.org>
AuthorDate: Thu Apr 23 12:18:51 2026 +0200

    feat: add `AGENTS.md` for basic coding rules
---
 AGENTS.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..62e71a4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,55 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+      https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Formatting
+
+### Javadoc
+
+1. **Wrap at 160 columns**, not 80.
+   Count the leading ` * ` prefix as part of the line.
+   Keep wrapping natural (do not break inside a `{@link ...}` or across a tag boundary if it can be avoided).
+2. **Getter summaries start with "Gets"; setter summaries start with "Sets".**
+   Prefer these verb forms over "Returns".
+   For non getter/setter methods keep a short verb phrase (for example "Configures", "Hardens", "Dispatches").
+3. **Javadoc style**:
+   Key rules:
+   - Open on its own line with `/**`,
+     close on its own line with ` */`,
+     align intermediate lines with a single leading ` * `.
+   - The first sentence is a short summary fragment.
+     It is the only part that appears in class/method index listings, so keep it self-contained.
+     Details (what is hardened, thread-safety, edge cases) belong in subsequent paragraphs, not bolted onto the summary.
+   - Separate paragraphs with a blank `*` line.
+     Prefix every paragraph *except the first* with a `<p>` tag at the start of the first word.
+     **Do** close with `</p>`.
+   - Block tags appear in the order `@param`, `@return`, `@throws`, `@deprecated`. No empty descriptions.
+   - Javadoc is present on every public class and every public or protected member,
+     with the standard exceptions (overrides, self-explanatory members, trivial `equals`/`hashCode`).
+
+### Prose
+
+- No em-dashes (`—`) in Javadoc, comments, commit messages, or documentation.
+  Use commas, colons, parentheses, or a fresh sentence instead. This applies to
+  HTML entities too (`&mdash;`).
+
+### Commits
+
+- Use the `Assisted-By:` trailer (not `Co-Authored-By:`).
\ No newline at end of file