Skip to content

Contributing.md

Latest commit

 

History

History
105 lines (75 loc) · 4.88 KB

Contributing.md

File metadata and controls

105 lines (75 loc) · 4.88 KB
Raw

Contributing Guide

Thanks for helping grow the Canton Developer Hub, This guide covers everything you need to know to add or update a tool listing.

There are two ways to contribute depending on what you want to do:

What you want How
Add/update a tool in the frontend catalogue/page Open a PR to tools.json and one MUST add their tool the same format as the others in the JSON File for it to be able to index properly.
Add/update a tool's entry in the markdown Dev Tooling Guide Open an Issue in this Repo with or Make a PR adding the Respective Tool's Details
Report a broken link or outdated info Open an Issue with the Tool and Source of claim.

Info on Adding a Tool to the frontend Catalogue Page (PR to tools.json)

The filterable page at the Developer Hub is powered entirely by tools.json in the root of this repo. To get your tool listed, add a new entry to that file and open a PR.

The entry format

{
  "name": "Your Tool Name",
  "maker": "Your Company or GitHub handle",
  "type": "partner",
  "category": "APIs",
  "desc": "One to two sentences describing what the tool does and who it's for. Be specific — generic descriptions get sent back for revision.",
  "links": [
    { "label": "Docs", "url": "https://your-docs.com" },
    { "label": "Repo", "url": "https://github.com/you/your-tool" }
  ],
  "daml_sdk_version": "3.4.11",
  "maintained_by": "Your Company"
}

The Daml SDK Version Requirement

This is a hard requirement. PRs that ignore it will not be merged.

If your tool uses, depends on, or is built against the Daml SDK, you must specify the exact version in the daml_sdk_version field:

"daml_sdk_version": "3.4.11"

Why this matters

The Daml SDK is versioned, and Canton Network itself moves forward on a regular release cadence. A tool built against an outdated SDK version may produce incorrect results, fail to compile against newer DARs, or be incompatible with current participant nodes. Listing a tool with a stale SDK version misleads developers and reflects badly on the ecosystem.

Your ongoing responsibility

You are responsible for keeping your listing. Specifically:

  • When a new Daml SDK version is released and you update your tool to support it, you must open a new PR updating the daml_sdk_version field in your entry.
  • PRs that update the SDK version should include a link to your tool's changelog, release notes, or commit that confirms the update.
  • If your tool falls more than one major version behind the current Daml SDK and no update PR has been submitted, your listing may be marked as outdated or removed at the maintainers' discretion.
  • You will not be notified individually when a new SDK version drops. It is your responsibility to track the Canton Network releases and the DPM changelog.

PR Checklist

Before opening your PR, confirm all of the following:

  • My entry is valid JSON.
  • All URLs are live and return a working page
  • type is exactly "official" or "partner" (no other values)
  • category matches one of the valid categories listed above
  • description is one to two sentences, specific, and free of marketing language
  • If my tool uses the Daml SDK, daml_sdk_version is set to the current version my tool is built against not null
  • maintained_by is filled in with the person or team responsible for keeping this up to date
  • I understand I am responsible for submitting a new PR if the Daml SDK version changes and I update my tool

Adding a Tool Entry to the Dev Tooling Guide Markdown Catalogue

The Canton Dev Toolings Guide.md file is the human readable catalogue. Longer descriptions, context, and usage notes for each tool.

To add or update an entry there, open an Issue (or a PR) using the template below. The maintainers will review and add it.

Issue template: New tool prose entry

**Tool name:** 
**Builder / Company:** 
**Category:** 
**Type:** official / ecosystem partner
**One-line description:** 
**Full description (2-4 sentences):** 
**Links:** 
**Daml SDK version:**

What Gets Rejected

To save everyone's time, these things will get a PR closed without merge:

  • Missing or null daml_sdk_version when the tool clearly uses the Daml SDK
  • type set to "official" for tools not maintained by Digital Asset or Canton Foundation
  • Broken or non-https links
  • Invalid JSON
  • Descriptions that are purely marketing copy with no technical substance
  • Tools that are not functional or publicly accessible (no private-access-only tools)
  • Duplicate entries for tools already listed

Questions?

Join the Canton Forum or open an Issue in this repo.