# How Are Contributions to the nts-servers Project Managed? A Complete Guide > Learn how contributions to the nts-servers project are managed with a detailed guide. Understand the pull request workflow including validation script updates and configuration regeneration. - Repository: [Jauder Ho/nts-servers](https://github.com/jauderho/nts-servers) - Tags: how-to-guide - Published: 2026-03-04 --- **Contributions to the nts-servers project follow a rigorous pull request workflow requiring validation via [`scripts/ntsCheck.sh`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntsCheck.sh), updates to the master [`nts-sources.yml`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml) file, and regeneration of derived configurations using [`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml) located in the repository root. According to the contribution guidelines in [`README.md`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntsCheck.sh) (referenced in [`README.md`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/AGENTS.md) file (line 5) specifies that new entries must be inserted in the correct alphabetical position within [`nts-sources.yml`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/chrony.conf), [`ntp.toml`](https://github.com/jauderho/nts-servers/blob/main/ntp.toml), and the formatted table in [`README.md`](https://github.com/jauderho/nts-servers/blob/main/README.md) (as documented in [`README.md`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml)** — The master YAML file containing all NTS server entries. All manual edits occur here. - **[`scripts/ntsCheck.sh`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntsCheck.sh)** — Bash utility for pre-submission server validation and reachability testing. - **[`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py)** — Python script that transforms [`nts-sources.yml`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml) into [`chrony.conf`](https://github.com/jauderho/nts-servers/blob/main/chrony.conf), [`ntp.toml`](https://github.com/jauderho/nts-servers/blob/main/ntp.toml), and README table entries. - **[`AGENTS.md`](https://github.com/jauderho/nts-servers/blob/main/AGENTS.md)** — Internal documentation specifying alphabetical ordering requirements and agent handling procedures. - **[`README.md`](https://github.com/jauderho/nts-servers/blob/main/README.md)** — Primary documentation containing contribution guidelines and workflow instructions. ## Practical Code Examples for Contributors Validate server reachability before submitting: ```bash # Replace with the hostname you intend to add ./scripts/ntsCheck.sh ``` Regenerate all derived configuration files after editing the master list: ```bash # 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: ```bash 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`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml) file. - Contributors must validate server reachability using [`scripts/ntsCheck.sh`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntsCheck.sh) before submission. - The [`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py) tool regenerates [`chrony.conf`](https://github.com/jauderho/nts-servers/blob/main/chrony.conf), [`ntp.toml`](https://github.com/jauderho/nts-servers/blob/main/ntp.toml), and README tables from the YAML source. - Entries must be alphabetically ordered by country as specified in [`AGENTS.md`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/README.md) specifically requires this validation step before merging. ### What derived files are generated from nts-sources.yml? The [`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py) script processes [`nts-sources.yml`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml) to generate three primary outputs: [`chrony.conf`](https://github.com/jauderho/nts-servers/blob/main/chrony.conf) for Chrony users, [`ntp.toml`](https://github.com/jauderho/nts-servers/blob/main/ntp.toml) for ntpd-rs configurations, and the formatted server table in [`README.md`](https://github.com/jauderho/nts-servers/blob/main/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`](https://github.com/jauderho/nts-servers/blob/main/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.