Contributing

These guidelines are a living document, and contributions from the TRACE modeling community are welcome.

How changes are made

This is an internal repository. Changes are made on a branch in the repository itself and merged through a pull request.

Do not fork

A pull request from a fork cannot be merged here. GitHub does not run Actions on fork pull requests for a private or internal repository unless that is explicitly enabled, and it is switched off for this organization. The required build and redaction-scan checks would never run, and without them the pull request can never merge — not even for an administrator. Ask for write access instead.

1. Ask a maintainer for write access. Membership of the NRC-Research organization by itself gives you read access, which is enough to clone and read but not to push a branch. A maintainer adds you as a repository collaborator with the write role.

   Write access does not let you merge anything — every change still goes through a pull request with an approving review.

2. Clone the repository:

   git clone https://github.com/NRC-Research/TRACE_guidance.git
   cd TRACE_guidance
   

3. Install the repository hooks before your first commit:

   export NRC_REDACTION_PATTERNS="$HOME/.config/nrc/redaction-patterns.txt"
   bash scripts/install-hooks.sh
   

   Ask a maintainer for the redaction pattern file if you do not have one. It is sent out of band and is never committed. Put the export line in your shell profile so it survives new shells.

4. Create a feature branch: git checkout -b feature/your-feature-name

5. Make your changes in the appropriate section, following the formatting rules in the contributing guide — particularly the rules for mathematical equations, which will not render if indented.

6. Preview locally with mkdocs serve, and confirm a clean build with mkdocs build --strict.

7. Sync with the latest main and resolve any conflicts:

   git fetch origin
   git rebase origin/main
   

8. Push the branch and open a pull request:

   git push -u origin feature/your-feature-name
   gh pr create --base main
   

Keep pull requests small

Small, focused pull requests are easier to review and less likely to conflict. Avoid large reformatting changes, and coordinate if several people are editing the same page. For a small correction you would rather not make yourself, open an issue instead.

What belongs in this guidance

This site is not a second copy of the TRACE manuals. Volume 2 of the User's Manual is organised by TRACE component and documents what each component does and how its input arrays are specified — cite it rather than reproduce it. This site is organised by plant system for a given reactor type, and its value is what the manual cannot contain.

A page earns its place when it answers what the manual does not:

• Applicable designs — which vendors and product lines, and where the guidance stops applying
• Nodalization actually recommended — cell counts, lengths, splits, and the reasoning, not just the input format
• The basis — why this choice and not another, with the supporting study cited where one exists
• Initialization and acceptance — what a converged steady state looks like
• Known failure modes — what goes wrong, how it presents, and the fix
• Provenance — which source document and section it came from

What does not belong

Restating component input specification. If a reader with Volume 2 open would learn nothing from the page, it is not yet doing its job.

Published documents committed as files. Cite the ADAMS accession. The originals under TRACE_ModelingGuidance/ are kept because they exist nowhere else; published manuals do not need a copy here.

Recommendations with no stated origin. A number with no source cannot be reviewed, updated or defended.

Say how settled the guidance is

Distinguish reviewed modeling recommendations from observations and proposals. Both are welcome — much of the value here is experience that has not been through formal review — but a reader must be able to tell which they are looking at. Identify the plant or facility, the source, and the applicable conditions.

Citations

Cite the specific section, equation or component, not just the document, and cite ADAMS accession numbers. The TRACE manuals carry no NUREG number, and several NUREG numbers previously used on this site belonged to unrelated reports — an unchecked citation is worse than none, because it looks checked. The manuals are revised per code patch, so state which revision a page depends on. See References.

Branch protection

main is protected. Changes must go through a pull request, each pull request needs one approving review, the branch must be up to date with main, and the build and redaction-scan checks must pass before it can merge. Pushing new commits to a pull request dismisses earlier approvals, so a revised pull request has to be approved again. GitHub does not accept an approval from the pull request's own author.

Repository administrators can merge without an approving review when necessary. The other rules apply to administrators as well: a pull request is still required, the checks still have to pass, and force pushes to main and deletion of main remain blocked for everyone.

Full contributing guide

The complete guide covers page templates, equation and code formatting, adding pages to the navigation, converting Word documents to Markdown, and the style rules used across this site:

Read CONTRIBUTING.md on GitHub

Contributing research and test reactor content

The Research and test reactor section is an outline awaiting contributions. Fill in an existing heading with modeling lessons, references, or supporting assessments — a complete chapter is not required.