How to submit a metric

  1. What reviewers look for
  2. What to have ready
  3. How to submit on GitHub
  4. What happens next

Step 3 of 4 How to submit on GitHub

Five steps in a web browser. Nothing here needs Git, a terminal, or any software installed.

Already comfortable with pull requests?

Skip this screen. It spells the browser flow out click by click so that submitting does not require knowing GitHub — but the submission itself is an ordinary pull request adding one file, and if that sentence was enough, you already know how.

The submissions repository is where the process actually lives, and its contributing guide holds the full instructions, the authoritative format specification and worked examples kept open so you can read a real review end to end.

  1. Make your own copy of the repository

    GitHub requires this before anyone outside NIST can propose a change. It takes one click and about five seconds, and you only do it once — if you have submitted before, you already have one.

    If you skip it and try to add a file, GitHub stops you with this:

    You need to fork this repository to propose changes.

    Sorry, you're not able to edit this repository directly—you need to fork it and propose your changes from there instead.

    That is not an error, and nothing has gone wrong. Click the green Fork this repository button, wait a few seconds, and you will land on a page that looks like the NIST repository but with your own username at the top — that is how you know it worked.

    Make my copy on GitHub

  2. Add your submission file

    In your copy, open the submissions folder and choose Add file → Create new file. Name it after your metric in lowercase with hyphens, ending in .yml — for example toxicity-score.yml.

    Paste in the template, then replace each value with your own. Delete any optional line that does not apply to your metric.

    Open the blank template

  3. Commit it, and start your pull request

    Click Commit changes…, then Propose changes in the box that appears. Accept the defaults on both — GitHub writes the file into your copy, then offers to open a pull request.

    That is what a submission is here: a pull request, or PR — the word reviewers, the repository and the rest of this guide use for it. It is one file plus a page where the review happens. Nothing has reached NIST yet; the last two steps are what send it.

  4. Tick all four boxes in the description

    GitHub then shows a description with a checklist. Every box must be ticked — change each [ ] to [x]. Reviewers rely on these, particularly the confirmation that your submission holds nothing confidential.

    This is the most common reason a first submission fails

    Leaving a box unticked makes the automated check report a failure — even though there is nothing wrong with your metric. It takes four clicks to avoid, and you can fix it afterwards by editing the description.

  5. Click Create pull request

    That is it. Your submission is with NIST, and maintainers are notified automatically. The next screen covers what happens from here.

If you get stuck

Nothing you do on your own copy affects the NIST repository, so there is nothing you can break by trying. If a screen does not look like the description above, the submission guide in the repository is the authoritative version.