search

AnssiR66 / AlanStdLib

The Standard Library for ALAN Interactive Fiction Language
Other
6 stars 2 forks source link

Roadmap to v2.2.0 #146

Open tajmone opened 2 years ago

tajmone commented 2 years ago

The list of pending things to be done before StdLib v2.2.0 is ready for release, to keep track of the work ahead. This is Issue should remain pinned until v2.2.0 is released, and updated whenever some tasks are solved or new ones are added.

For fine-grain details on some planned changes, see also:

Unfortunately, due to the sporadic work on the project, we currently don't have yet a clear roadmap for v2.2.0 (e.g. Dashboard Projects and Milestones), partly because some of the spotted problems still need testing and assessing before we can decide on the course of action to take, and partly because some Issues are about library enhancement which we haven't yet decided whether they should be conditional to the v2.2.0 release or could be postponed.

This Issue (and the comments below) should help track the scattered discussions and allow us to narrow down the scope of what has to be done before v2.2.0 is ready for release.

Repository and Toolchain

Library Code

These are either bug-fixes, design flaws, improvements or new features which need to be completed before the code for v2.2.0 is ready:

Documentation & Assets

We also need to complete work on the new StdLib documentation (AsciiDoc port) before we can release v2.2.0, and make sure the old extra code assets are up-to-date too — See #91

AnssiR66 commented 2 years ago

Hi Tristano, many thanks for the excellent round-up on things that are on the to-do-list before StdLib 2.2.0 is ready for release. Yes, there are still a number of issues to be handled, and the question where to start /and what to leave for a later release needs to be tackled. I haven't had time to dedicate to this project lately and it has been looming somewhere in the background.

Let me go through the list you provided, over the next few days, and deem the importance of the various issues. I will then present the list to you and we can see whether we agree on the importance/urgency of the various points.

About the manual, of course the new features need to be added and explained there, but I don't know how much I can be of help with the "entire revisiting" - I naturally made the original manual to the best of my abilities to be as clear and helpful as possible. So, to do an entire revisiting I would need to have a clearer vision of what is needed (I remember we discussed this, so I need to go back to those discussions) rather than just do things differently "for its own sake", I mean, without understanding why things need to be changed, and how (apart from adding the new features to the existing manual, and tweaking a couple of passages here and there).

In general, I would have only a limited time for this project presently, due to the end of term hurries at school, -for the next month or so. Also. in the summer, when I have free time, I am concentrating on a book writing project which I haven't been able to focus on during the school year. So, progress with Alan would be probably slow, as far as my contributions are concerned, but it is of course good to make at least some progress than none at all 🙂.

So, I will be in touch after some time, after going through the open issues, and let's think forward from there. You can of course also say which issues should be solved first and foremost, and which can be left for later.

best, Anssi

From: Tristano Ajmone @.> Sent: Wednesday, April 20, 2022 12:45 PM To: AnssiR66/AlanStdLib @.> Cc: Subscribed @.***> Subject: [AnssiR66/AlanStdLib] Roadmap to v2.2.0 (Issue #146)

The list of pending things to be done before StdLib v2.2.0 is ready for release, to keep track of the work ahead. This is Issue should remain pinned until v2.2.0 is released, and updated whenever some tasks are solved or new ones are added.

For fine-grain details on some planned changes, see also:

Unfortunately, due to the sporadic work on the project, we currently don't have yet a clear roadmap for v2.2.0 (e.g. Dashboard Projects and Milestones), partly because some of the spotted problems still need testing and assessing before we can decide on the course of action to take, and partly because some Issues are about library enhancement which we haven't yet decided whether they should be conditional to the v2.2.0 release or could be postponed.

This Issue (and the comments below) should help track the scattered discussions and allow us to narrow down the scope of what has to be done before v2.2.0 is ready for release.

Library Code

These are either bug-fixeshttps://github.com/AnssiR66/AlanStdLib/issues?q=is%3Aissue+is%3Aopen+label%3A%22%3Askull%3A+bug%22, design flawshttps://github.com/AnssiR66/AlanStdLib/issues?q=is%3Aissue+is%3Aopen+label%3A%22%3Askull%3A+design+flaw%22, improvements or new features which need to be completed before the code for v2.2.0 is ready:

Documentation

We also need to complete work on the new StdLib documentation (AsciiDoc port) before we can release v2.2.0.

— Reply to this email directly, view it on GitHubhttps://github.com/AnssiR66/AlanStdLib/issues/146, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ABO2KHU7YZSYDGTVPBKCP6TVF7G35ANCNFSM5T3OSQ2A. You are receiving this because you are subscribed to this thread.Message ID: @.***>

tajmone commented 2 years ago

Ciao Anssi! Don't worry about the ETA. In theory it's supposed to be out in June of this year, which should be possible in terms of code fixes, since most of the open Issues seem rather small or optional fixes, and in most cases it's just a case that providing a few examples and good documentation is more than enough (e.g. the non-clothing wearables can be implemented as is, although in future editions the system might be fine tuned).

Surely, the StdLib Manual is the bulk of the work ahead of us. I think I can manage to come up with a clean draft for the Summer, but probably not so for the Cook Book, since work didn't even start there. I think I'm still fresh enough on the code to just go ahead and write/update the Man text and code examples, but indeed there are a few code problems that should be fixed before I do, lest I have to revise the docs once more (e.g. the extra wearer attribute is a useful feature worth adding, not much work either, so it's not worth documenting the clothing class until that's done).

In any case, I'll keep you up to date on the work in progress, as usual, via tasks-lists, flash news, etc., so you can review changes when you do have time.

Also. in the summer, when I have free time, I am concentrating on a book writing project which I haven't been able to focus on during the school year

Sounds cool. Is that a novel or a teaching book? For novels, I've had a chance to test many dedicated writing software and tools, so if you need some tips on some good novel-writing tool don't hesitate to drop me an email!

AnssiR66 commented 2 years ago

Ok Tristano! So, if the manual is the most important thing we should concentrate on, I won't give a separate list of the other issues in terms of what is more crucial and what is less so, if most of them are small bug fixes or polishes anyway. But please let me know where I could be of help in updating the manual, I can of course provide bits and pieces here and there as needed.

The book project I mentioned is not a novel but Swedish grammar exercises. I am a teacher of English and Swedish at a vocational institute, and I thought it might be a good idea to collect some of the exercises that I've made over the years, together with a number of fresh ones, and put them in a book form. But the novel-writing software and tools you mentioned sound intriguing, can you just give a quick overview of what kind of tools you are using?

tajmone commented 2 years ago

Began Working on The Manual

Ok @AnssiR66, I've began working on the StdLib Manual again (began updating Ch.18 Restricted Actions). My reasoning is that this is the most important thing which is blocking the new library release. From what I can see, the unresolved Issues can all be postponed to the second-next release — after all, they affect mostly edge-cases which, and these problems were already there for a very long time, yet no one reported them.

So, it's now much better for us to focus on finally releasing the new library version, so end users can benefit from the many improvements that are already there. Once the Manual is updated we can simply release, and then address all pending Issues in future updates.

About the manual, of course the new features need to be added and explained there, but I don't know how much I can be of help with the "entire revisiting" ...

Don't mention it! It's been so long I've put my hands on it that I'm struggling too. Good job I've annotated here and there the various things to be done, but still ... some chapters are still as in the original, just ported from Word to AsciiDoc without text changes (usually these don't have any annotations).

The hard part is working out how to reorganize the various sections to avoid redundancy and make better use of Asciidoctor cross references and book partitioning. In any case, I think that the best way to approach this task is to:

  1. Start working on a topic at the time, ensuring that all new changes are covered first.
  2. Then revisit all the old sections on features that were not changed, converting all examples to dynamic code and ensuring they work with the current library code.
  3. As I proceed with the above steps I'll disseminate the text with admonitions annotating things to be done, and add to each chapter a "Section Status" sidebar, so we can quickly check each chapter's progress.

Reorganizing the book is a bit more challenging. Right now, the Manual is neither a reference guide nor a step-by-step learning book, but rather a mixture of both. My idea is to try to present the library features in an order which makes sense for the beginner, but trying at the same time to preserve an organization that is also friendly for looking up specific topic.

Once I've gone over the entire text multiple times, and have a firmer grasping of what's where, I should be able to roughly split the book into various parts:

  1. An Intro Part, with general info and guidelines on how to setup a new project, etc.
  2. A Library Overview Part, where the various features are briefly presented, providing cross references to chapters/section where each feature is fully presented.
  3. A Library Features Part, where all features are presented in detail, organized by grouping related features together.
  4. A Coding Guide Part, presenting practical examples on how to use the StdLib in real adventures, integrating custom code with the library and/or tweaking the library source.
  5. An Appendices Part, with the various consultation tables, quick references, etc.

Currently the Manual is already more or less organized this way, except for the Coding Guidelines, which are currently interspersed all over the place. This is the main area where I'd like to intervene in terms of contents, separating the presentation of the various features from all the usage tips.

I think this makes sense, because the Manual should document the library features in depth, providing practical examples, etc., but in terms of comparing how a certain "effect" in an adventure can be implemented, that should go in the Coding Guide Part, because often the same effect can be achieved in different ways.

The goal is to avoid having too much info in the Library Features Part, which should really be a sort of reference guide. E.g. right now there are often recopies on how to mimic a library feature with bare ALAN code, which sort of drifts away from the main point, which is just covering how each feature works. Instead, we should provide cross-reference links to the Coding Guide Part, where the reader can find practical examples and comparison of the different ways a same task can be achieved (using different library features, or even without the library).

Basically, the StdLib Manual should be readable in two ways: to learn from scratch, and as a quick reference for consultation. Most likely newbies will read it from start to end the first time, but from there they'll need just to consult it on specific features while working on an actual adventure project.

I'm not sure whether it will be ready by June, but I doubt it. There's a lot of work to be done with the dynamic code examples — which is worth the price, since all examples and transcripts will always mirror the library code status after that, and any errors would be caught in real time. In some cases, these examples are only for internal use, but in other cases we'll be shipping the example source code with the library, which is an added bonus for the users.

Probably by the last week of May I'll be able to provide a more realist estimate of when the documentation could be ready. If we don't manage to make it ready by mid June we might as well slip all the way to end September, since the June goal was to provide a release that end-users could employ to create their adventures during the Summer holidays.

Even if we end up releasing by September it wouldn't be too bad — after all, the release candidate is still available, which in terms of features is pretty close to the current codebase. The most important thing is to come up with a well polished StdLib Manual — maybe this first new edition won't be perfect, but it has to be good, cover all new features, and preserve all the previous topics (no losses in the process).

Hopefully, once the first AsciiDoc edition is ready, all future work and updates will be much simpler thanks to the new repository set-up and its automated toolchain.

AnssiR66 commented 2 years ago

Your outline certainly sounds good. We can proceed accordingly and see what kind of time frame we need for the proposed changes and other tasks. It looks like a lot to do but once we get to it, it doesn't necessarily feeel that daunting. I think the trick to do is to use the existing materials as much as possible.

tajmone commented 2 years ago

I think the trick to do is to use the existing materials as much as possible.

I totally agree on this, and that's how I'm proceeding.

The main problem is that all the original text and its examples need to be verified by converting the example snippets into real adventures, so that we can verify that they (still) work as described, since often the code snippets are old and don't work any more.

I think that converting the snippets into real sample adventures (whether for internal documentation use only, or as shipped source files) is the most time-consuming aspect in all this.