From 638dea4e553dc58a3ec3532e15676b7d18e8bf34 Mon Sep 17 00:00:00 2001 From: Ryan Prior Date: Wed, 5 Nov 2025 19:31:27 +0000 Subject: [PATCH 1/3] Adds contribution guide --- CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ec1f875 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing to xc + +Thank you for using `xc` and for your interest in contributing. Please take a moment to get familiar with our guidelines. + +## Be Courteous +We expect you to read and follow our [Code of Conduct](./CODE_OF_CONDUCT.md) and to conduct yourself always in a way that creates a positive environment and clearly demonstrates your courtesy. + +## Use GitHub Issues + +We track and discuss work using Issues. Please [open an issue](https://github.com/joerdav/xc/issues/new/choose) to discuss changes before sending a pull request. We may close a PR without review if it's opened without discussion, especially by an unknown contributor. Whether we choose to review a PR is based on a judgment call about the maintenance burden it adds. + +## Write Tests, Maintain Coverage + +We expect authors of net-new code to provide tests covering the new code. Prior to merging, CI will verify that all tests pass and that coverage equals or exceeds the pre-merge state. + +## Document Your Work + +We expect contributors to keep documentation (in `docs/`) up to date, reflecting all substantive changes. Use `xc run-docs` (requires `hugo`) to verify that your changes build successfully & look as you expect. + +# HOWTOs + +## Add Support For A Markup Language +We aim to support popular, stable, lightweight plain-text markup languages. Our priorities for language support: +- New languages should work as similar to the Markdown implementation as possible +- Users should be able to read and maintain tasks without writing excessive markup or understanding implicit behavior +- The implementer wants to actually maintain `xc` tasks using the new language (we won't add languages just to have them) + +Steps to add support: +- Create a GitHub issue to propose the addition and discuss +- Fork the repo and add a new parser module for the new language under `parser/` + *It may be advantageous to copy an existing parser and modify it to fit the particulars of the new addition.* +- [Write tests](#write-tests-maintain-coverage) & test fixtures in your parser module that cover all the same cases as are present in `parser/parsemd/testdata/` +- Update the `cmd/xc/` module to use your parser +- [Document your work](#document-your-work) +- Send a PR for your changes, linking the issue you created previously From 49c1ad3782c4051fb64bcc2ee4625bbe1504f1f2 Mon Sep 17 00:00:00 2001 From: Ryan Prior Date: Wed, 5 Nov 2025 19:36:23 +0000 Subject: [PATCH 2/3] Adds "contributing" link to readme --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index ace5d12..203503b 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,9 @@ tasks) as a source of useful commands for the project. Installation instructions are described at . +# Contributing +Find our guidelines & HOWTOs at [CONTRIBUTING.md](https://github.com/joerdav/xc/blob/main/CONTRIBUTING.md). + # Features - Tasks defined in Markdown or org-mode files as code blocks. From cf4f48c4990bf709279e4e214e2aa65c441d35fd Mon Sep 17 00:00:00 2001 From: Ryan Prior Date: Thu, 6 Nov 2025 22:08:35 +0000 Subject: [PATCH 3/3] Clarifies maintenance expectation for new markup languages --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ec1f875..5a181ef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,7 +23,7 @@ We expect contributors to keep documentation (in `docs/`) up to date, reflecting We aim to support popular, stable, lightweight plain-text markup languages. Our priorities for language support: - New languages should work as similar to the Markdown implementation as possible - Users should be able to read and maintain tasks without writing excessive markup or understanding implicit behavior -- The implementer wants to actually maintain `xc` tasks using the new language (we won't add languages just to have them) +- New languages should be ubiquitous enough that it makes sense for the project to take on the maintenance burden to support them going forward. See for example the [list of markup languages supported by GitHub](https://github.com/github/markup/blob/master/README.md#markups) to get a rough idea. Steps to add support: - Create a GitHub issue to propose the addition and discuss