Making The Repo and Codebase More Accessible

[tajmone]

I would like to propose some improvements in terms of documenting the repository (README files, etc.), the source code by adding more comments on what does what, and of course the Wiki, which should provide extra info with more freedom in terms of what one wishes to unravel.

Having spent some time sifting through the ALAN source code, I got the impression that adding some extra comments here and there might make it easier for users who approach the codebase for the first time — the project is quite big, and it also contains/uses some legacy third party modules/tool which might not be so well known today.

It would also be nice to have documents explaining what's what in the compiler and interpreter subfolders, since along with the C sources there are various test files, compiler generator files, etc., so having a commented list of the files (or the various file extensions at play) would simplify grasping the big picture of what's in these folders.

I still haven't quite understood why there are some many branches in the project (instead of just tags pointing to the various releases), and which branch is used for the latest development — this is worth mentioning in the main README.

So, if it's OK with you, I could create an Issue for specific requests which I have in mind (and maybe create some associated labels, or even a Project or a Milestone), and keep discussing here more general ideas and suggestions.

[thoni56]

There are many thoughts that come to mind as a result of your suggestion:

1. I have added a few drawings to the design document, which I think should be the primary source for the overall knowledge you are seeking. (And it is published at https://git.io/alan-docs!)
2. I will (hopefully) continue updating that document since I'm into some kind of architecture/design phase and wanting to explore that further with one of my hobby projects as vehicles, possibly Alan.
3. I'm not a fan of creating a lot of issues for things that might not happen, to me that pollutes visibility and makes it harder to find what's really crucial (and currently that is UTF-8 and synonyms). I also like to have issues not as work items, but primarily for request for changes to the functionality (and bugs). ("Change requests" not "Chores") Creating issues as representations of "Chores" also increases Work In Progress and I actually feel that I have opened up to many items within the Alan domain already.
4. Alan is a hobby project and I want to keep it that way ;-) In my work I see too much of working after overfilled "structured" lists, in my hobby projects I need to feel that I can work on whatever my spirit tells me.

Having said that I can feel you ;-) But perhaps those questions would be better as discussions? I'm happy to try to answer, perhaps we together can find formulations that can fit in the design documentation.

And you are probably right that there are some basic "README"s that probably should exist.

And as a final comment, I strongly believe in not doing anything that is not driven by a "real" need. If you are interested in looking at the sources, then we are two (probably) and we can manage it without filling yet another list with "good to have" items. If, and when, there are more people interested, this urgency rises, and then we should definitely work in this area. At this point I feel the needs of the user community (including you ;-) is much more valueable to fulfil. But if you feel that these new (and not bad) ideas and requests are the most important I should focus on, then... Well, perhaps then we need to talk about that ;-)

So I suggest you open up discussions for your questions. Those will also help me understand what needs to be clearer, in code or documentation and we can figure out what to do about it along the way.

Ok?

[tajmone]

I'm totally fine with your considerations, especially about polluting Issues with chores that might pile-up and stale out.

I'm about the read the whole updated Alan Design Documentation — also, as far as design questions are concerned, its ADoc source might be a good place where to add some comments about missing topics, etc., since that document is a good candidate for answers.

I strongly believe in not doing anything that is not driven by a "real" need. If you are interested in looking at the sources, then we are two (probably) and we can manage it without filling yet another list with "good to have" items. If, and when, there are more people interested, this urgency rises, and then we should definitely work in this area. At this point I feel the needs of the user community (including you ;-) is much more valueable to fulfil. But if you feel that these new (and not bad) ideas and requests are the most important I should focus on, then... Well, perhaps then we need to talk about that ;-)

My worry when it comes to IF is always continuity. I've seen so many excellent IF projects and websites simply disappear in the course of time. Somehow, users tend to give for granted that official websites will always be available, until they no longer are and everyone starts panicking about who might have saved a copy of something, etc. And when it comes to codebases and source projects, lack of design docs and commented sources can easily become an obstacle for legacy continuation — especially with tools that have aged and depended on very old libraries which might no longer be available or usable, and need be replaced by more modern modules.

So I believe that good comments (though for posterity) are always a good choice. Some of the classing IF authoring tool have become hard to compile nowadays (some even using MSVC 6!) and reviving them requires some major refactoring, which is going to be hard (and not very motivating) if the source are not well commented, and the design not documented. In so many decades (almost half a century of witnessed IF, from the age of home computer to the present) we've all witnessed how interest in the genre tends to swing like a pendulum — big waves of interest are usually followed by periods of calm indifference which can last years (during which OS introduced many problematic changes that might hinder recompiling those tools).

I'm not saying any of this is a top priority, but it's a good idea to keep in mind the long term goal, and maybe fill in some gaps now and then.

Also I've noticed that when an IF system become too old, people tend to re-implement them in more modern languages, which usually abstract away much of the cross-platform complexity thanks to modern standard libraries. Hence comments (and design docs) should also useful for someone looking at re-implementing the code (or parts of it) in another language — modern languages offer go foreign functions interfaces, so it's easier to incrementally port a project from C to another language, or just replace obsolete modules with libraries in the other language.

Or maybe someone wants to create a JavaScript ALAN interpreter to run in the browser (like was done for Hugo and many other IF systems), a task for which comments can be more precious than the C code itself some times.

Ultimately, it would be nice if someone armed with the ALAN Design document and the will to read through the ALAN sources could be able to carry on the legacy in whichever language he/she prefers.

Just think of how puzzling the whole ISO encoding can be to someone who's in his twenties today, and probably never worked with non Unicode source and text files (I'm not even sure he/she might understand the real efforts behind those encodings, and the struggles with limited memory and storage which people had to deal with in those days).

But I'm sure that one bit at the time this will be achieved.

[thoni56]

Again, I feel you.

No disagreement, only concern that overburdoning (one of the wastes in Lean) me/us might lead to the opposite, lack of inspiration and stamina, in turn leading to Alan just dying. So it's a balance. I want to be able to continue this for years to come. And be able to help anyone attempting a re-implementation...

But I'm happy that you bring these things up, so that I/we can keep that in mind going forward with this project that still gives me/us joy and satisfaction.

BTW, the idea of commenting on the design document is very good. The comments in The Manual were easy to address, they were in context and I could just "fix them". These comments will probably be more "problematic" given the less mature state of The Design Document. But I say, let's try that with your questions. And if there is anything that doesn't fit there, we could open a discussion about it, which is also something that will be preserved for posterity.

[thoni56]

I still haven't quite understood why there are some many branches in the project (instead of just tags pointing to the various releases), and which branch is used for the latest development — this is worth mentioning in the main README.

There are two reasons for the many branches. One is that at one point the previous CVS repository was migrated to git using a script that created many branches.

The second is that early on, when moving between platforms was more cumbersome, a common pattern was to create a tag when releasing the "main" platform from the main branch. Any changes that were necessary to make that release happen was made on a separate branch for that release work, created at that tag, and the later merged back. When the release for another platform was started the same procedure applied. This is why many end with _branch, the first part was the name of the "bud" tag for the release "point".

As we can see many of those "release work" branches have a few, one or no commits. We could probably go through those 79 branches and see which contains useful commits, but I think that is over-doing it. Over time we should probably replace (at least) the branches with no extra commits with a tag with the same name. Some branches could even be considered obsolete (or of no value any longer) and be removed.