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 (`—`).
+
+### Commits
+
+- Use the `Assisted-By:` trailer (not `Co-Authored-By:`).
\ No newline at end of file