How Are Contributions to the nts-servers Project Managed? A Complete Guide

Contributions to the nts-servers project follow a rigorous pull request workflow requiring validation via scripts/ntsCheck.sh, updates to the master nts-sources.yml file, and regeneration of derived configurations using scripts/ntpServerConverter.py before submission.

The jauderho/nts-servers repository maintains a curated list of Network Time Security (NTS) servers. Understanding how contributions to the nts-servers project are managed ensures that new time sources meet quality standards and are correctly propagated to all downstream configuration formats.

The nts-servers Contribution Workflow

1. Submit Changes via Pull Request

All additions or modifications must be submitted as a Pull Request that edits the master data file nts-sources.yml located in the repository root. According to the contribution guidelines in README.md (lines 14-15), this YAML file serves as the single source of truth for all NTS server entries.

2. Validate Server Reachability

Before a PR can be merged, contributors must verify that the proposed NTS server is operational. The repository provides scripts/ntsCheck.sh (referenced in README.md lines 27-28) to test connectivity and NTS handshake capabilities. Run this script against the target hostname to ensure the server responds correctly before submission.

3. Provide Required Metadata

Each entry in nts-sources.yml must include complete server metadata: the hostname, stratum level, geographic location, owning organization, and relevant operational notes (such as virtualized or anycast deployment details). This structured data enables accurate categorization and filtering.

4. Maintain Alphabetical Order by Country

The AGENTS.md file (line 5) specifies that new entries must be inserted in the correct alphabetical position within nts-sources.yml, sorted by country. This ordering convention ensures the list remains organized and predictable for automated processing.

5. Regenerate Derived Configuration Files

After editing nts-sources.yml, contributors must run the conversion script to propagate changes to all derived formats. Execute scripts/ntpServerConverter.py nts-sources.yml to automatically regenerate chrony.conf, ntp.toml, and the formatted table in README.md (as documented in README.md lines 14-16).

6. Verify a Clean Diff

Before finalizing the PR, verify that only intended changes are present. The contribution workflow recommends running git diff origin README.md chrony.conf ntp.toml to review modifications to the generated files (referenced in README.md line 16). This step prevents accidental inclusion of unrelated changes.

7. Use Signed Commits

While not strictly mandatory, the project prefers signed commits for authenticity verification. The README.md (line 11) notes that signed commits are preferred, adding a layer of trust to contributions.

Essential Files in the Contribution Process

Understanding the repository structure helps contributors navigate the workflow efficiently:

• nts-sources.yml — The master YAML file containing all NTS server entries. All manual edits occur here.
• scripts/ntsCheck.sh — Bash utility for pre-submission server validation and reachability testing.
• scripts/ntpServerConverter.py — Python script that transforms nts-sources.yml into chrony.conf, ntp.toml, and README table entries.
• AGENTS.md — Internal documentation specifying alphabetical ordering requirements and agent handling procedures.
• README.md — Primary documentation containing contribution guidelines and workflow instructions.

Practical Code Examples for Contributors

Validate server reachability before submitting:

# Replace <NTS_SERVER_NAME> with the hostname you intend to add

./scripts/ntsCheck.sh <NTS_SERVER_NAME>

Regenerate all derived configuration files after editing the master list:

# Convert the master YAML into chrony.conf, ntp.toml and README entries

./scripts/ntpServerConverter.py nts-sources.yml

Verify only expected changes are staged before committing:

git diff origin README.md chrony.conf ntp.toml

Summary

• All contributions to the nts-servers project require a Pull Request modifying the master nts-sources.yml file.
• Contributors must validate server reachability using scripts/ntsCheck.sh before submission.
• The scripts/ntpServerConverter.py tool regenerates chrony.conf, ntp.toml, and README tables from the YAML source.
• Entries must be alphabetically ordered by country as specified in AGENTS.md.
• Signed commits are preferred for authenticity, and clean diffs should be verified before finalizing PRs.

Frequently Asked Questions

What is the master file for adding NTS servers?

The master file is nts-sources.yml located in the repository root. All new NTS server entries must be added to this YAML file, which serves as the single source of truth for the entire project. The file is then processed by conversion scripts to generate all other configuration formats.

How do I verify an NTS server is working before submitting?

Run the scripts/ntsCheck.sh script with the target hostname as an argument. This utility tests NTS connectivity and handshake capabilities to ensure the server is operational before you include it in your Pull Request. The README.md specifically requires this validation step before merging.

What derived files are generated from nts-sources.yml?

The scripts/ntpServerConverter.py script processes nts-sources.yml to generate three primary outputs: chrony.conf for Chrony users, ntp.toml for ntpd-rs configurations, and the formatted server table in README.md. These derived files should never be edited manually.

Are signed commits required for nts-servers contributions?

Signed commits are not strictly mandatory but are strongly preferred according to the contribution guidelines in README.md (line 11). Using signed commits adds a layer of authenticity and trust to your contributions, helping maintain the integrity of the curated server list.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}