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 <[email protected]> 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
