Skip to content

Fork Sync: Update from parent repository #176

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
github-actions wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Fork Sync: Update from parent repository #176

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 87 additions & 5 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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),
Expand All @@ -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]
Expand All @@ -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 <same options as the original 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
Expand All @@ -386,14 +437,38 @@ 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

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):

Expand Down Expand Up @@ -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
Expand Down