[BUG] Update `DIRECTORY.md` file (semi-)automatically

[Panquesito7]

Description

There's a script to build the DIRECTORY.md file. However, there's no workflow or anything that creates it automatically.
The users won't be able to see a list of algorithms. There's also a broken link in the readme.

I propose to create a GitHub Actions workflow to build it automatically on every push (not pull_request as this could mess up the PR branch) if there are any changes.
With protected branches, there's no way to push directly, but a pull request can be created by GitHub Actions, and then reviewed by the maintainers.

What do you think about this? 🙂

[dlesnoff]

There are currently two problems with the script directory.nim:
– new repositories from other branches are untracked by default on local directories. That means scripts within directories created in another branch appear in the generated DIRECTORY.md file.
– There is no enforced capitalization. We could enforce lowercase except for the first letter and except for proper names like Viterbi, Karatsuba, Luhn, etc …
The script is okay as it is, as I do not want to maintain an algorithm to decide whether a name is proper and the GitHub Action would determine the DIRECTORY.md file in the remote repository solving the first issue.

I am not sure to understand why you prefer to create another branch rather than modifying the pull request's branch. Would it be that much terrible to modify the pull request directly?
Creating another branch would artificially double the number of commits in the commit history. It adds manual work.

[ZoomRmc]

– There is no enforced capitalization. We could enforce lowercase except for the first letter and except for proper names like Viterbi, Karatsuba, Luhn, etc …

The titles inferred from the file names are Title Cased unless the unit has a canonical title in the first line (iff it's a doc comment) of the file. Maintaining the dictionary of canonical title spellings is unfeasible, so I intended to lay this responsibility on unit authors.

– new repositories from other branches are untracked by default on local directories. That means scripts within directories created in another branch appear in the generated DIRECTORY.md file.

Not sure WDYM here. Do you mean the situation of working on different branches at the same time and the fact that the script takes the state of the working tree for granted and is ignorant of the git state?

[dlesnoff]

Sorry, these issues have nothing to do with the script itself.
I agree with you that management of correct title spelling is unfeasible, we can leave it as it is.
We may have to untrack files by default and explicitly add the files tracked in .gitignore. Otherwise the script adds any untracked file from other branches, since those are not git ignored. Files from other branches stay in the repository across branches if there are inside an untracked directory.

I will give an example. Let us say we are in the main git branch.
We want to add algorithm X, so we create a new branch and checkout into it:

git checkout -b algorithmX

Now, algorithm X is a mathematical algorithm, so we put it into a new maths directory.

mkdir maths
touch maths/algorithmX.nim
git commit -am "Add algorithm X"

If we checkout again in the main branch, here is what git status returns:

git checkout main
git status -s

?? maths/

If we run directory.nim

nim r .scripts/directory.nim > DIRECTORY.md
git commit -am "chore: Update DIRECTORY.md file"

Then the DIRECTORY.md contains the algorithmX entry.

[dlesnoff]

Actually, since we can not have per-branch .gitignore files, my proposed solution to exclude all files by default and add each one of them would not work.

[ZoomRmc]

Ok, so I understood you correctly.

Depending on the planned use-case:

1. Run the script automatically after merging PRs: this problem doesn't occur.
2. Require authors to use the script as the part of their PRs:
   a. Require authors to stash-clean the working tree before updating:

   git stash --include-untracked
   nim r .scripts/directory.nim > directory.md
   git add directory.md # unnecessary if the repo already tracks the file
   git commit directory.md -m "Update directory,md"
   git stash apply
   

   b. Automate the above from the script iteself

[dlesnoff]

2.a. is a terribly complex solution for beginners. It would discourage people from contributing.
So 1. or 2.b.
Notice that option 1, in addition to doubling the commits, it may require a second maintainer to merge a single P.R. when there is any problem with the directory.md file.
2.b in a Git Hook/Github Action seems fine to me.

[Panquesito7]

I am not sure to understand why you prefer to create another branch rather than modifying the pull request's branch. Would it be that much terrible to modify the pull request directly?

It could mess up people's work if they're about to push a change and similar stuff like that.
Also, running the workflow on every push will also ensure there are no DIRECTORY.md merge conflicts on other PRs.