diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..f5aacaf --- /dev/null +++ b/README.md @@ -0,0 +1,238 @@ +# td + +[pt][pt1] | [fr][fr1] | [eo][eo1] | [es][es1] + +[pt1]: https://euandreh.xyz/td/pt/ +[fr1]: https://euandreh.xyz/td/fr/ +[eo1]: https://euandreh.xyz/td/eo/ +[es1]: https://euandreh.xyz/td/es/ + +Minimalistic bug tracker CLI. + +Create and maintain a `TODOs.md` file for bug tracking. + +It is a tool for distributed, offline issue tracking, reified as a simple text +file in the repository. + + + +## Usage + +```shell +# inside a Git repository +# create the basic configuration + +$ echo 'TD_USE_BUILTIN_HOOKS=git' > .tdrc + + + +# create a sample task + +$ td -cm 'Implement feature A' +File "TODOs.md" doesn't exist yet, creating a brand new one. +[main 9d854ac] TODOs.md: Add #td-1c1e8f92-ed60-1a5b-89d9-cb2b140e498b + 1 file changed, 4 insertions(+) + create mode 100644 TODOs.md +#td-1c1e8f92-ed60-1a5b-89d9-cb2b140e498b added to TODOs.md. + + + +# register a bug, and edit its content with $VISUAL + +$ td -t bug -m 'Fix B' +Type "bug" doesn't exist yet, creating new section with it. +[main 0f79796] TODOs.md: Add #td-1794611e-bfd7-9de5-3e71-cd0dcb3a1d77 + 1 file changed, 10 insertions(+) +#td-1794611e-bfd7-9de5-3e71-cd0dcb3a1d77 added to TODOs.md. + + + +# add new task, with its initial state as DOING + +$ td -cm 'Work on C' -s DOING +[main 1be9c00] TODOs.md: Add #td-1bbc2775-49b4-6112-5a9b-8f7fa466997c + 1 file changed, 3 insertions(+) +#td-1bbc2775-49b4-6112-5a9b-8f7fa466997c added to TODOs.md. + + + +# create custom task type, and use it to # register a new task + +$ cat <<'EOF' >> .tdrc +export TD_TYPES=' +task:Tasks +issue:Issues +idea:Ideas +' +EOF +$ td -cm 'Fix D' -t issue +Type "issue" doesn't exist yet, creating new section with it. +[main 7b888e3] TODOs.md: Add #td-231e1472-d32f-69d0-6c62-b924b70a5b7f + 1 file changed, 6 insertions(+) +#td-231e1472-d32f-69d0-6c62-b924b70a5b7f added to TODOs.md. +``` + +--- + + +The final `TODOs.md` file is: + +```commonmark +# Tasks + +## DOING Work on C {#td-1bbc2775-49b4-6112-5a9b-8f7fa466997c} +- DOING in 2022-01-16 + +## TODO Implement feature A {#td-1c1e8f92-ed60-1a5b-89d9-cb2b140e498b} +- TODO in 2022-01-16 + + +# Bugs + +## TODO Fix B {#td-1794611e-bfd7-9de5-3e71-cd0dcb3a1d77} +- TODO in 2022-01-16 + +--- + +B must be fixed. + + +# Issues + +## TODO Fix D {#td-231e1472-d32f-69d0-6c62-b924b70a5b7f} +- TODO in 2022-01-16 +``` + + + +## Installation + +```shell +$ make +$ make check +# make install +``` + +You can pass `PREFIX` or `DESTDIR` to `make` if you'd like: + +```shell +$ make PREFIX=$HOME/.local +$ make check +$ make install PREFIX=$HOME/.local +``` + +There are no dependencies or requirements, only standard tools such as +POSIX sed, POSIX make, etc. + + +## Documentation + +### Manuals + +The documentation is available via installed manpages or online. +Start with +[`td.tutorial.7`] ([pt][pt4], [fr][fr4], [eo][eo4], [es][es4]), and see the rest +afterwards: + +- [`td.1`] ([pt][pt2], [fr][fr2], [eo][eo2], [es][es2]): CLI usage + reference; +- [`tdrc.5`] ([pt][pt3], [fr][fr3], [eo][eo3], [es][es3]): `.tdrc` file + format reference; +- [`td.tutorial.7`] ([pt][pt4], [fr][fr4], [eo][eo4], [es][es4]): getting + started and tutorial for starting to use td; +- [`td.recipes.7`] ([pt][pt5], [fr][fr5], [eo][eo5], [es][es5]): common HOWTOs + and usage recipes; +- [`td.why.7`] ([pt][pt6], [fr][fr6], [eo][eo6], [es][es6]): motivation and + explanation of why create this tool. + +[`td.1`]: https://euandreh.xyz/td/en/td.1.html +[pt2]: https://euandreh.xyz/td/pt/td.1.html +[fr2]: https://euandreh.xyz/td/fr/td.1.html +[eo2]: https://euandreh.xyz/td/eo/td.1.html +[es2]: https://euandreh.xyz/td/es/td.1.html +[`tdrc.5`]: https://euandreh.xyz/td/en/tdrc.5.html +[pt3]: https://euandreh.xyz/td/pt/tdrc.5.html +[fr3]: https://euandreh.xyz/td/fr/tdrc.5.html +[eo3]: https://euandreh.xyz/td/eo/tdrc.5.html +[es3]: https://euandreh.xyz/td/es/tdrc.5.html +[`td.tutorial.7`]: https://euandreh.xyz/td/en/td.tutorial.7.html +[pt4]: https://euandreh.xyz/td/pt/td.tutorial.7.html +[fr4]: https://euandreh.xyz/td/fr/td.tutorial.7.html +[eo4]: https://euandreh.xyz/td/eo/td.tutorial.7.html +[es4]: https://euandreh.xyz/td/es/td.tutorial.7.html +[`td.recipes.7`]: https://euandreh.xyz/td/en/td.recipes.7.html +[pt5]: https://euandreh.xyz/td/pt/td.recipes.7.html +[fr5]: https://euandreh.xyz/td/fr/td.recipes.7.html +[eo5]: https://euandreh.xyz/td/eo/td.recipes.7.html +[es5]: https://euandreh.xyz/td/es/td.recipes.7.html +[`td.why.7`]: https://euandreh.xyz/td/en/td.why.7.html +[pt6]: https://euandreh.xyz/td/pt/td.why.7.html +[fr6]: https://euandreh.xyz/td/fr/td.why.7.html +[eo6]: https://euandreh.xyz/td/eo/td.why.7.html +[es6]: https://euandreh.xyz/td/es/td.why.7.html + +### Directory structure + +The directory structure of the repository is: +- `aux/`: personal scripts and helpers I've vendored in to ensure the + repository is self contained, feel free to ignore it; +- `doc/`: manpages, with their translated versions; +- `po/`: gettext `.po` files for the translated languages and hunspell + dictionaries for spell checking; +- `src/`: main source code for the project; +- `tests/`: integration tests for the project. + + +## Contributing + +Extra tools used for development are: +- [ShellCheck] for validating scripts; +- [po4a], [mdpo] and [gettext] for i18n and l10n support; +- [pandoc] for generating the documentation HTML and website. + +[ShellCheck]: https://www.shellcheck.net/ +[po4a]: https://po4a.org/index.php.en +[gettext]: https://www.gnu.org/software/gettext/ +[pandoc]: https://pandoc.org/ +[mdpo]: https://mdpo.readthedocs.io/en/master/ + +For running the extra development-only checks, run: + +```shell +$ make dev-check +``` + +and for generating the documentation HTML and website, run: + +```shell +$ make public +``` + +Send contributions to the [mailing list] via +[`git send-email`](https://git-send-email.io/). + + +## Links + +- [homepage](https://euandreh.xyz/td/en/) +- [source code](https://euandreh.xyz/td.git/) +- [bug tracking](https://euandreh.xyz/td/TODOs.html) +- [mailing list] +- [CI logs](https://euandreh.xyz/td/ci.html) +- [CHANGELOG](https://euandreh.xyz/td/en/CHANGELOG.html) + +[mailing list]: https://lists.sr.ht/~euandreh/public-inbox?search=%5Btd%5D + + +## Releases + +- [v0.1.0](https://euandreh.xyz/td.git/commit/?id=v0.1.0) [td-v0.1.0.tar.gz](https://euandreh.xyz/td.git/snapshot/td-v0.1.0.tar.gz) ([sig](https://euandreh.xyz/td.git/snapshot/td-v0.1.0.tar.gz.asc)) - 2021-06-13 + + +## License + +The code is licensed under +[GNU Affero General Public License v3.0 or later][AGPL-3.0-or-later] +(AGPL-3.0-or-later). + +[AGPL-3.0-or-later]: https://euandreh.xyz/td.git/tree/COPYING |