Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Roadmap to v2.2.0 #146

Open
2 of 23 tasks
tajmone opened this issue Apr 20, 2022 · 6 comments
Open
2 of 23 tasks

Roadmap to v2.2.0 #146

tajmone opened this issue Apr 20, 2022 · 6 comments
Labels
🕑 progress status
Milestone
Release 2.2.0

Comments

@tajmone
Copy link
Collaborator

tajmone commented Apr 20, 2022 •
edited
Loading

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

  • MAIN GUIDES
  • QUICK GUIDES
  • OTHER DOCS — we'll probably need to provide the following docs:
    • StdLib v2.2.0 Migration Guide — illustrating changes and new features between v2.1 and v2.2.0, with guidelines on how to adapt adventures written for StdLib v2.1.
@tajmone tajmone pinned this issue Apr 20, 2022
@tajmone tajmone added this to the Release 2.2.0 milestone Apr 20, 2022
@AnssiR66
Copy link
Owner

AnssiR66 commented Apr 23, 2022 via email

@tajmone
Copy link
Collaborator Author

tajmone commented Apr 23, 2022

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
Copy link
Owner

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
Copy link
Collaborator Author

tajmone commented May 2, 2022

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
Copy link
Owner

AnssiR66 commented May 4, 2022

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
Copy link
Collaborator Author

tajmone commented May 4, 2022

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
🕑 progress status
Projects
None yet
Milestone
Release 2.2.0
Development

No branches or pull requests
2 participants
@AnssiR66 @tajmone