Giters

alan-if / alan-docs

Alan IF Documentation Project

Home Page:https://git.io/alan-docs

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Add "What's New"/"Changelog" Section

tajmone opened this issue · comments

commented

REJECTED — Issue was turned down after careful consideration (see below). Ingore it.

With the release of Alan Beta7 the new AsciiDoc generated ALAN Manual will officially replace the previous PDF from ODT version.

We should add a new "What's New" or "Changelog" Chapter (or Appendix?) to list all the new language features and changes since the last Beta release.

Because the last ODT/PDF version related to Alan Beta5, in the upcoming release we should cover the changes for Beta6 and Beta7 — the Beta6 are already available in the CHANGELOG file that ships with the release.

The Beta7 changes can be looked up in the various commits, or is there already a changelog under work in the dev branches?

  • Add "What's New" section and cover:
    • Beta7 Changes
    • Beta6 Changes

Of course, in the actual Manual we might want to provide a more friendly version of the changelogs, with xref links wherever possible, and some extra text if it might help the reader.

commented

I'm not sure I agree with this due to the extra manual work it will add. I already do a manual CHANGES.txt to web-page CHANGES conversion. I'd hate to do more of that sort ;-) Of course that is for the Alan language. And I suppose that if the manual clearly states which version of the language/system it refers to we don't need to repeat this info in the document. But a pointer to the website info about changes or the Changes.txt would be good.

Then we are left with changes in the document itself, and there might be some value in showing if there are any radical differences from the previous version. One such recent example is the addition of actual information in AppG.

But, again, I like to not have to do a lot of manual work for things that are of limited value or can be found elsewhere. (I remember when we used to write all changes to source code in the source code. Terrible... Thank god for version control!)

Who would benefit from such a list? Probably only persons that have already read the document and would be interested to see if there is anything new they could learn from. But chances are that they already have a manual. So that leads me to the conclusion that any "News" is most valuable in the announcing of a new version of the document. Also, having a Changes section begs the question how far back should this go, only between this and the last version? Or all versions? And to which level of detail?

But all this depends on how we look at the document and its versions. I have always leaned towards "this is the best available now, I hope it is good enough for you, otherwise there will be a new version soon". So there has been a manual released with the release of Alan but each snapshot has a, possibly updated, version of the manual too.

So, I don't look at the manual as a "book" that will be released. To me it is more of a piece of text that evolves gradually, and we will do our best to make it better.

This partly relates to the branching discussion. The only thing I think is important is that we have an "official" version that is in sync with the features in the last released SDK. So for any text changes that relates to new features should be kept separate (on a separate branch). Any other changes should continuously evolve the master, making the "offical, in-sync" version better with each commit.

This became another "rant", sorry for that. Can't help myself from expressing my thoughts on these matters.

So, in short, I suggest not adding a Changes section. Instead I suggest keeping track of significant changes through the commits and when we do new a release of the Alan system the Changes might have a few "Documentation:" type bullets. Thus looking at the Manual as a part of the complete Alan SDK, and as far as possible release it at the same time. (It should just be a matter of merging any text changes for new features, and set a release tag.)

Thoughts?

commented

Yes, I agree, it would just add extra maintenance burden (we came to the same conclusion for the StdLib Manual, were we've dropped entirely similar sections, along with the sections for those who are coming from Lib v1.0, etc.). So, yes, let's keep it DRY.

This partly relates to the branching discussion. The only thing I think is important is that we have an "official" version that is in sync with the features in the last released SDK. So for any text changes that relates to new features should be kept separate (on a separate branch). Any other changes should continuously evolve the master, making the "offical, in-sync" version better with each commit.

Actually, I think what you said elsewhere is even better in terms of avoiding problematic merge entanglements:

  • master branch will always show the ALAN Manual as it was updated and publicly released for/together-with a given ALAN Beta release (e.g. Alan 3.0beta7, etc.).
  • A dev branch (specifically dedicated to the Manual, e.g. dev-man) should host any updates to the book (regardless of whether they deal with Alpha or Beta features).

This would mean that we never have to worry about conflicting Manual sources, we only work on the dev-man branch, and use master for public releases of the book, which is usually associated with a new ALAN Beta release.
Of course, it would also mean that the official Manual won't be updated until the next ALAN Beta release (which can take quite some time), but it's also true that if we use a fixed name for the Manual dev branch (e.g. dev-man), end users will always be able to access the latest PDF/HTML edition via direct links to the dev branch.

It makes sense, after all author will probably fall in one of these two categories:

  1. Those who work only with the latest Beta release.
  2. Those who always update to the latest Alpha release.

The former can rely on the book distributed on the ALAN website (or master branch, here); the latter can fetch/consult the latest book from the dev branch.

So far, we've been including updated PDF/HTML versions of the book in the dev branch, for previewing and reviewing purposes practicality (if not with every committed change, at least with significant changes). It would be safe to assume that the Manual on the dev branch would be the best choice for authors working with Alpha releases, because as soon as a new feature is added to ALAN we'll probably document it in the dev branch.

As for the fact that the official version of the Manual might be kept on hold as long as a new Beta release is out (which could be anywhere between a month and a couple of years) and that end users won't benefit from added contents to the book, I don't think this is going to be a problem — it's just like the Beta vs Alpha release, were one has either to wait for the benefits of bug fixes and new features.

Also, I've learned that new features to the language are quite rare, and are usually announced in the mailing list and covered in the Changelog; and they are also easy to understand, being small additions (albeit they might have huge implications).

Ultimately, "Beta users" prefer stability, whereas "Alpha users" prefer riding the cutting edge. By offering direct links to both official previews of the manual (master branch) and development snapshots (dev-man branch), we should covering all needs.

Branch Strategy Suggestions

In view of the above discussion, I suggest that we:

  1. Rename the current beta7-prep branch to dev-man, and will henceforth only use it for updates to the ALAN Manual (and no other docs).
  2. Use/keep the betaX-man-<feature> naming scheme to indicate old development branches that were already merged into the dev baseline, for archival purposes. The betaX-* naming scheme helps associating those branches with the ALAN version the were targeting.

@thoni56, what do you think of the above branches naming strategy? We could embrace it right away, or maybe after the first official release (no hurry right now, except for renaming the merged branches that we wish to keep for archival purposes).

commented

@tajmone I think the reasoning and naming sounds fine. When I wrote the comments above I was thinking about what we have been talking about also somewhere before, your model of two types of changes to the manual, "editorial" (changes to layout, spelling, grammar and other minor corrections) and "features" (content additions related to changes in the SDK).

But as those are not clear-cut and in view of the entanglement of them even for smaller changes, I think the 2-branch-only strategy is sound. As far as I can see we now have a "clean" such situation (beta7-prep and friends all lined up and branched off of HEAD of master) it is an ideal starting point for such a change, so let's go for it.