From bd3449ce1961b3e36e9e38b5989baa229527af42 Mon Sep 17 00:00:00 2001 From: Ralph Castain Date: Thu, 9 Jul 2026 12:36:35 -0600 Subject: [PATCH] Import portable contributor rules from the PMIx AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The PRRTE AGENTS.md and its PMIx counterpart share the same authorship and much of the same guidance, but the PMIx file had accumulated several general, project-agnostic rules that PRRTE's copy was missing. Carrying them over keeps the two orientation guides consistent so an agent moving between the code bases meets the same expectations, and it fills real gaps in the PRRTE guidance around style, hygiene, and process. Added: the conditional-spacing style rule; a directive to update .gitignore for any build product a change introduces; the "never bend a test to accommodate a bug" testing rule; a shared-repository/worktree section warning against repo-wide git commands; the preference for C++-style comments; commit-message guidance (body line wrapping, no AI tooling attribution, incidental fixes as standalone commits); and a maintainer-mode caution for build-system edits. While porting the build-system guidance, correct an over-broad claim in the existing text: because PRRTE builds in maintainer mode, editing a Makefile.am does not require the full autogen.pl plus configure cycle — a plain make regenerates the affected Makefiles. Also repair a garbled duplicate line in the copyright-header rule. Signed-off-by: Ralph Castain --- AGENTS.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 87 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f89cc0d573..5b5a57fe74 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -202,7 +202,6 @@ Do not use `PMIX_` or `pmix_` prefixes for new PRRTE symbols. ### New files need the standard copyright/license header. -Copy the multi-institution BSD header block — including the `Copyright (c) 2026 Nanook Consulting All rights reserved. Copy the multi-institution BSD header block — including the `$COPYRIGHT$` and `$HEADER$` tokens — from a neighboring file. If you substantially change an existing file, add your copyright line to its block. @@ -231,6 +230,17 @@ Use `{ }` around every conditional or loop body, even single-line ones. 4 spaces, never tab characters. +### Spacing on conditional statements + +Use a space to separate the condition from the surrounding keywords — +write `if (condition) {`, not `if(condition){`. When a condition spans +multiple lines, put the combining operator at the end of the preceding +line: + +```c +if (condition1 || + condition2) { +``` ### Stay compiler-warning-free @@ -245,6 +255,18 @@ be warning-free before submitting. Do not modify files produced by autotools (`configure`, `Makefile.in`, etc.), pre-rendered documentation, or third-party vendored code. Edit the source code instead. +### Update `.gitignore` for build products you introduce + +If your change adds a new source file, component, or generated artifact +that the build produces something new from — a new executable or test +binary, a newly generated source/header, an object or library in a +directory that did not have one before — add the resulting build product +to the appropriate `.gitignore` so it does not show up as an untracked +file. Never commit the build product itself; ignore it. Check +`git status` after a clean build to confirm no generated file you created +is left untracked, and match the nearest existing `.gitignore` pattern +style (many component directories carry their own `.gitignore`). + ### GOLDEN RULE: regenerate `show_help` content after touching any help file The `show_help` messages are embedded into the binary from a generated @@ -315,7 +337,8 @@ buffers unless interfacing with PMIx routines that require it. ### C standard PRRTE targets C11. Do not add `-Wno-*` flags to suppress warnings — -fix the underlying issue. +fix the underlying issue. C++-style `//` comments are allowed and +preferred. ### Use the `__prte_attribute_*__` macros for compiler attributes.** [`src/include/prte_config_bottom.h`](src/include/prte_config_bottom.h), @@ -338,8 +361,11 @@ the git repository; it is produced by running: ./autogen.pl ``` -This must be re-run whenever `configure.ac`, any `Makefile.am`, or any -`*.m4` file under `config/` is modified. After `autogen.pl`: +This must be re-run whenever `configure.ac` or any `*.m4` file under +`config/` is modified. Editing a `Makefile.am` does **not** require the +full `autogen.pl` + `./configure` cycle — PRRTE builds in maintainer +mode, so a plain `make` regenerates the affected `Makefile[.in]` files and +completes the build. After `autogen.pl`: ```sh ./configure [options] @@ -363,6 +389,31 @@ Common configure options: Version requirements: PMIx ≥ 6.1.0, hwloc ≥ 2.1.0, libevent ≥ 2.0.21. +### Modifying the configure / build system + +Editing the build system means regenerating it — `make` alone can't, and +trying will wedge the tree. If you change `configure.ac` or any +`config/*.m4` file (including the embedded oac/Autotools macros), the +change does not take effect until the build system is regenerated. Do +not rely on a plain `make`: PRRTE builds in maintainer mode, so `make` +auto-triggers a partial in-tree Autotools regeneration that frequently +fails (e.g., unexpanded `OAC_*` macros, `config.status` errors) and can +leave the tree half-regenerated and unbuildable. Instead, regenerate and +reconfigure explicitly: + +```sh +./autogen.pl +./configure +make -j +``` + +Recover the original configure invocation options from the existing tree +with `./config.status --config` (or read the header of `config.log`). +This process is slow but mandatory after any build-system source change — +there is no safe shortcut. As noted above, editing a `Makefile.am` alone +is the exception: a plain `make` regenerates the relevant `Makefile[.in]` +files and completes the build without the full cycle. + --- ## State Machines @@ -386,6 +437,23 @@ Key job states in order: `PRTE_JOB_STATE_INIT` → --- +## Working in a shared repository + +Don't assume you're the only agent (or person) using this clone. In +particular, if you're working in a **git worktree**, other worktrees may +be active against the same underlying repository at the same time. Avoid +repo-wide git commands that reach outside your own working area and can +disrupt others — for example, `git worktree prune`, or `git stash` +(which writes to the repository-wide stash ref shared by all worktrees). +Keep your git operations scoped to your own branch and worktree. + +As a narrow exception, creating a **new branch** when you need to park +work in progress (for example, instead of `git stash`) is fine. Just be +careful not to collide with branches that other agents or people may be +using in the same clone — pick a clearly-scoped, unlikely-to-clash name. + +--- + ## Contributing ### Commit messages @@ -393,7 +461,14 @@ Key job states in order: `PRTE_JOB_STATE_INIT` → Write prose commit messages, not bullet lists. The subject line should complete the sentence "If applied, this commit will …". The body must explain **why** the change is needed, not just what it does. Keep the -subject line under 72 characters. +subject line under 72 characters, and wrap body lines at around 75 +characters. Don't add AI tooling attribution to commit messages. + +Keep incidental fixes as their own commits. Small "drive-by" bug fixes +you notice while working on something else are welcome, but it is usually +best to land them as standalone commits, separate from your main change, +so each can be evaluated and reviewed on its own. One logical change per +commit keeps history reviewable and easy to bisect. All commits require a `Signed-off-by:` line (DCO): @@ -431,6 +506,13 @@ pterm # shut down DVM For resource manager integration (SLURM, PBS, LSF), test within an actual allocation on the relevant system. +**Never bend a test to accommodate a bug.** Do not weaken, skip, or +rewrite an existing test — and do not craft a new one — merely to make +buggy behavior pass. Tests encode intended behavior: when one fails, the +default assumption is that the code is wrong, not the test. If you find a +genuine bug in the code base, identify it, report it, and where +appropriate fix it — don't paper over it in the test suite. + ### Reporting bugs File issues at https://github.com/openpmix/prrte/issues. Include the