path: root/TODOs.md

# Tasks

## TODO Generate commit log by author {#task-1554614f-2e33-616d-d021-70828dbf0381}
- TODO in 2021-09-10

---

The hardest part I can think of is what to put on the URL.
Using URI encoding may work, but it'll look very ugly.

## TODO Add link to SVG generated `makefile2graph` to `README.md` and the tool itself as a dependency {#task-543193c9-b1c5-9362-b69d-d7b6e5e071f0}
- TODO in 2021-08-28

## TODO Add integration tests of `libgistatic.a` and `gistatic.h` {#task-54ab2440-45aa-5bf8-388c-43f8a5dbbd9c}
- TODO in 2021-08-28

## TODO Make sure functions like `escape_html()` is handling Unicode (UTF-8) correctly {#task-4202ee33-1344-0854-c970-89664066b029}
- TODO in 2021-08-24

## TODO Verify there is no implicit dependency on the order of evaluation of arguments {#task-fbb258cd-f95d-af86-cc7b-0c324d2ae42b}
- TODO in 2021-08-24

## TODO Fix `.gitdir/index` files from embedded repositories being updated after running `make check` {#task-b1290a2e-271f-dea6-8217-1452a11ec3de}
- TODO in 2021-08-23

## TODO Assert paths created with `strjoin()` or `strsjoin()` do not exceed `PATH_MAX` {#task-e51e6490-c42c-1167-2d2a-26af8b8cd654}
- TODO in 2021-08-22

## TODO Check for duplicated `git_commit_lookup()` calls {#task-c71e7a3a-076d-3553-e245-0ad2b7a64231}
- TODO in 2021-08-22

---

This could lead to race conditions where a commit happens while gistatic itself
is running, and grabs different commits for a branch, for example.

## TODO Run `tests/build-sample.sh` with Valgrind and sanitizers {#task-218e2893-c2d3-caa5-b0e3-cde70b31a3f7}
- TODO in 2021-08-22

## TODO Add languages bindings {#task-a0634ded-968e-bce5-3fef-8e1c5e3aab35}
- TODO in 2021-08-21

## TODO Dark mode for favicon {#task-9eb2fad6-359b-f221-7dec-490acebe80f5}
- TODO in 2021-08-20

## TODO Add explanation of directory structure to `README.md` {#task-2ac45f7a-7152-d296-ab36-b0f60e2db3cb}
- TODO in 2021-08-20

## DONE Build a `libgistatic.a` and `gistatic.h` and include in "install" target {#task-62a25249-fc96-2774-9df9-663216fc6a0c}
- DONE in 2021-08-20

  Done in
  [`f19bc2e5d08d8e306faf25d970686f87fc5ccec1`](https://git.euandreh.xyz/gistatic/commit/?id=f19bc2e5d08d8e306faf25d970686f87fc5ccec1)
  and
  [`1618274ac68c11b5e17112984e7bc538c7880445`](https://git.euandreh.xyz/gistatic/commit/?id=1618274ac68c11b5e17112984e7bc538c7880445).
- TODO in 2021-08-19

## TODO Write a `mkdir_p` for use on the output directory {#task-4e40832e-78cf-fc21-cbf9-2fe00fd3828d}
- TODO in 2021-08-19

---

Maybe put it in a dedicated file.

Make sure the input argument doesn't exceed `PATH_MAX`;

## TODO Handle tag updates {#task-ab32196c-88e9-f329-f9a1-63499a29a47c}
- TODO in 2021-08-18

---

If a tag is force-pushed, update the tarballs that are derived from it.

## TODO Assert catgets limits in `test_underscore` such as catlog length and message length {#task-b690c658-67ac-6390-ac37-1dc961503ea2}
- TODO in 2021-08-17

---

Do the same for the translated catalogs.

## DONE Separate `gitstatic_main` out of `main` {#task-d6cab5ad-0405-5190-f918-766b81daf8c0}
- DONE in 2021-08-20

  I chose against having an allocator parameter.
  I find this choice would be more appropriate if gistatic would be running on
  exquisite places, such as WASM or embedded systems.
  Instead, gistatic is meant to run on any POSIX system (where libgit also
  works).

  Done in
  [`80c61292dca6b5965c626f7fa1b83da940d0fe91`](https://git.euandreh.xyz/gistatic/commit/?id=80c61292dca6b5965c626f7fa1b83da940d0fe91).
- TODO in 2021-08-17

---

Make it receive an allocator parameter, and enable building a `libgistatic.a`
library too and receiving a top-level allocator parameter.

## TODO Have a PRNG so I do not depend on `/dev/urandom` {#task-e99fa50b-75ea-21fb-6b4d-84447646cdea}
- TODO in 2021-08-13

## DONE Create `libgistatic.a` {#task-2e2ad57f-9c31-69d8-e3d9-2708c2b73403}
- DONE in 2021-08-06

  Duplicate of [`#task-62a25249-fc96-2774-9df9-663216fc6a0c`](#task-62a25249-fc96-2774-9df9-663216fc6a0c).
- TODO in 2021-08-06

---

Keep `src/gistatic.c` mostly as it is, and move the `main()` to a `src/main.c`
or `src/cli.c` file, and build the executable from there.

## TODO Remove spaces around `git clone ...` when copying to clipboard in the browser {#task-cd214149-a183-9bd3-292a-d48b3fb85050}
- TODO in 2021-08-02

## TODO Add description to submodules {#task-5b4b46b6-b1e8-6ba0-4f26-fab9de6a0e75}
- TODO in 2021-07-31

## TODO Create an "honest list of drawbacks" {#task-b3d67f87-c55a-a9b6-c9f8-c2f57d2f5803} tag:docs
- TODO in 2021-07-31

---

Inspired by [Purelymail](https://purelymail.com/).

Add both to the `README.md` and to the manpages.

Current items:
- can't compare commits: this
  requires `O(n!)` code and HTML to be generated;
- can't display human-friendly date formats like "3 days ago", only timestamps;
- can't handle big repositories, only small and medium ones;

## TODO Integrate `fallible` or other form of fault injection into the test suite {#task-ca8d80ae-9d31-5dfa-03de-b3cfccf2a8b2}
- TODO in 2021-07-31

## DONE Add CSS media query for dark mode {#task-07c14c08-3757-ced7-36f8-d1ec5c437633}
- DONE in 2021-08-20

  Done in
  [`580259c41b653d72e96f6bb941565a0df5c9ac1f`](https://git.euandreh.xyz/gistatic/commit/?id=580259c41b653d72e96f6bb941565a0df5c9ac1f).
- TODO in 2021-07-31

## TODO Translate `README.md`, `CHANGELOG.md` and `src/gistatic.msg` {#task-21d7dcb9-adfe-e8d6-64fa-39d5972b5d83}
- TODO in 2021-07-31

---

- [ ] `README.md`
- [ ] `CHANGELOG.md`
- [ ] `src/gistatic.msg`

## TODO Add Valgrind, sanitizers and fuzzers to the test suit {#task-a6bdaeb0-7099-c728-2b7c-b080aa2fba33}
- TODO in 2021-07-31

---

Tools references:
- [sanitizers] from clang
- [LibFuzzer], also from clang
- [clang-tidy]
- [Milu], mutation testing

Links I found useful:
- <https://developers.redhat.com/blog/2014/10/16/gcc-undefined-behavior-sanitizer-ubsan>
- <https://www.jetbrains.com/help/clion/google-sanitizers.html#makefiles-compdb>
- <https://www.youtube.com/watch?v=FP8zFhB_cOo>

[sanitizers]: https://clang.llvm.org/docs/
[LibFuzzer]: https://llvm.org/docs/LibFuzzer.html
[clang-tidy]: https://clang.llvm.org/extra/clang-tidy/
[Milu]: https://github.com/yuejia/Milu

When using accumulating the test corpus, how to maintain it?
Is this something one would erase from time to time?
Or is this something that could and should be kept alonside the fuzz targets
themselves?
If they are to be kept, how to manage them?
Make periodic tarballs and put them on a server somewhere?
After all, commiting this data is completly undesirable.
Maybe creating periodic tarballs, make torrent files for those and commit the
torrent files themselves.
By also creating some simple tooling to keep old tarballs versions around on my
machine and on a web server (to serve as a "web seed"), than this effectively
allows sharing of the corpus.
By also creating some simple tooling to keep old tarballs versions around on my
machine and on a web server (to serve as a "web seed"), than this effectively
allows sharing of the corpus.

## DONE Embed `src/unit-test.{c,h}` into `src/gistatic.c` {#task-ae96e5b6-ab04-3a3d-1777-b28031273a19}
- DONE in 2021-07-31

  Done in
  [`d843a40a039936b4d9b2b7b7552b88e9944bdd95`](https://git.euandreh.xyz/gistatic/commit/?id=d843a40a039936b4d9b2b7b7552b88e9944bdd95).
- TODO in 2021-07-31

## TODO Add explanation and comparison to stagit and CGit {#task-39e71afe-4ac9-4c3d-97e4-9ac41f826089}
- TODO in 2021-06-11

## CANCELLED Synchronize Cargo.toml version and Makefile {#task-09018dd8-f1a2-4b0b-a56f-dea9fdc78d99}
- CANCELLED in 2021-08-01

  Not applicable: it is not Rust, but C.
- TODO in 2021-05-31

---

The version in the Makefile is the primary one.

## TODO v0 Overview {#task-946c7f4f-2b97-40ff-b620-5fc241900709}
- TODO in 2021-03-05

---

- [ ] hierarquical tree view, per branch and per commit
- [ ] show notes in commit
- [ ] `tarballs/` folder, with `.tar.gz` and `.tar.gz.asc` files
- [ ] generate tarballs for all tags and all branches
- [ ] SHA in log
- [ ] `.patch` files (with `git format-patch --stdout -1 $SHA`), raw view
- [ ] blame view, with history
- [ ] highlight code
- [ ] render markdown
- [ ] leverage `cloc`
- [ ] Atom feed of commits and releases
- [ ] use mustache for generating HTML and Gemini files

Benchmark on (stagit):

- Git: 60k commits, 100MB repository
- Guix: 75k commits, 311MB repository
- Nixpkgs: 275k commits, 2.5GB repository
- Linux: 1M commits, 2,5GB repository


# Bugs


# Improvements


# Questions

## TODO What does `int restrict *p` mean? {#question-ab994373-9c09-c4f9-07cf-962f64443231}
- TODO in 2021-09-08

## TODO Can one change the font? {#question-93d85890-41dd-f856-a6f9-801d948f76ce}
- TODO in 2021-08-17

---

When using assistive technology, or just ordinary browser configuration, can the
user change the font: be it size, family, weight, etc.?
What about on mobile?

## TODO Should there be an alt for the logo images? {#question-87b2068f-85dd-25e9-b0c6-5e41fbbb04ca}
- TODO in 2021-08-17

---

For the index of repositories, the logo isn't a link.
At most, it is a link to itself, which isn't really useful.
In this case, an alt like "Logo image of the repository list" isn't as useful,
and a description of the actual image itself after its purpose would be better.

For the repository pages, the logo is a link to the index page, and this role is
more relevant.
Beyond the description of the logo, a phrase stating that it is a link to the
repository list is probably a good thing.

## DONE How to embed repositories without using submodules {#question-5414aee2-031a-5759-2a22-d572ee899ac0}
- DONE in 2021-08-04

  By using a special `.gitdir` directory on the embedded repositories, the toplevel repository
  can remain unchanged and include those.

  Done in
  [`252430e9ea5996c21c1fe24de623f458a24edbb7`](https://git.euandreh.xyz/gistatic/commit/?id=252430e9ea5996c21c1fe24de623f458a24edbb7).
- TODO in 2021-07-31

---

I want to embed repositories so that I can use them in unit and integration
tests, but making them submodules makes the repository much less standalone than
I would like.


# Decisions

## DONE Duplicate stylesheet and logo {#decision-c725e140-99fb-802d-f5ad-44577593212a}
- DONE in 2021-08-17

---

The `style.css` and `logo.svg` files are being duplicated when generating the
HTML for the repository and for the index of repositories.

Right now, I'm choosing to keep it that way.

The reasoning is: when generating the HTML for a repository, this process is
self-contained, and doesn't depend on the existence of a index of repositories
in the parent directory.

## DONE Perl vs C {#decision-d349b5be-3e00-4e00-a110-0eb7f402d4ab}
- DONE in 2021-05-28
- TODO in 2021-03-06

---

Instead of Perl vs C, it became Perl vs Rust, and I've chosen Rust.

I choose Rust over C because it is a higher-level language than C is.
It allows me to produce binaries and libraries without extra dependencies (unlike C++'s `libstdc++`), and I can deal with memory management without reference counting (unlike Nim) or garbage collection (unlike D).

I'm favoring Rust as a C-like tool because it allows me to write code that transcends the language barries: with C/Rust code, a `.so` library can be consumed by any programming language on any environment.
The binary application that will be the CLI could be written in any language, also, but it is done so in Rust for convenience.

So the question of Perl vs C now is becoming applicable only on more specific scenarios: when having a `libsomething.so` isn't worth anything.
This isn't the case for this library.


# Resources

- [How are zlib, gzip and zip related? What do they have in common and how are they different?](https://stackoverflow.com/questions/20762094/how-are-zlib-gzip-and-zip-related-what-do-they-have-in-common-and-how-are-they)
- [GZIP file format specification version 4.3](https://datatracker.ietf.org/doc/html/rfc1952)
- [ZLIB Compressed Data Format Specification version 3.3](https://datatracker.ietf.org/doc/html/rfc1950)
- [A simple tar implementation](https://github.com/calccrypto/tar)
- [libtar - C library for manipulating tar files](https://github.com/tklauser/libtar)
- [`static int write_tar_entry()`](https://git.kernel.org/pub/scm/git/git.git/tree/archive-tar.c?id=daab8a564f8bbac55f70f8bf86c070e001a9b006#n242) from Git itself (which is what CGit uses)
- [zlib-ng](https://github.com/zlib-ng/zlib-ng): zlib replacement with optimizations for "next generation" systems
- [jzlib](https://github.com/ymnk/jzlib): re-implementation of zlib in pure Java
- [pako](https://github.com/nodeca/pako/): high speed zlib port to javascript, works in browser & node.js


# Scratch

https://stackoverflow.com/questions/424839/what-were-the-main-disadvantages-of-cgi-bin-based-web-development
https://www.careerride.com/mchoice/cgi-disadvantages-servlets-925.aspx
https://www.geeksforgeeks.org/common-gateway-interface-cgi/
https://stackoverflow.com/questions/28907546/disadvantages-of-using-cgi-scripts-written-in-c-for-web-server-side
https://www.quora.com/What-are-the-advantages-and-disadvantages-of-CGI-programming?share=1
https://www.nginx.com/resources/wiki/start/topics/examples/fastcgiexample/


i18n
https://github.com/projectfluent/fluent/wiki/Fluent-and-L20n
https://github.com/projectfluent/fluent/wiki/Fluent-vs-gettext
https://github.com/projectfluent/fluent/wiki/Fluent-and-ICU-MessageFormat