Re: [Mingw-cross-env-list] What happened to version numbers?

[Volker Grabsch]

Stefan Löffler schrieb:
> On 2012-04-21 10:59, Nikos Chantziaras wrote:
> > I just pulled release 2.22 of MXE, but the makefiles don't have
> > package version numbers anymore.  For example, previously they had:
> >
> >   $(PKG)_VERSION  := 1.2.3
> >
> > Now that line is missing.  What happened?  How do I modify the
> > makefiles to use my preferred versions instead?
> 
> Version numbers were moved to index.html. I guess it's easier to filter
> than parsing all Makefiles.

Since this is a recurring question, and sice I haven't yet
found the time to adjust the "creating new projects" tutorial,
I think I should add some explaination about it. Although I'll
have to speak verbosely, please bear with me. I'll make my point. :-)

The documentation concept of MXE is best summarized as:

    website = documentation = repository content

With the first equation "website = documentation" I mean
that I hate it when projects keep their website and their
documentation as if those were two separate things. They
usually overlap in many areas, meaning multiple places which
are easily getting out of sync over time. To avoid that
hassle, I decided to make our website to *be* the documentation.
It worked astonishingly well! You can view it both ways: First,
we have website that contains the full documentation. Second,
we have a documentation that looks like a project website.

With the second equation "documentation = repository content"
I mean that I hate it when projects have "documentation wikis"
which diverge from the "real documentation". The Wiki is in
some database on the webserver, while the API doc is maintained
in the source repository. So why having two or three separate
places for documentation? Why not simply accepting improvements
to the documentation the same way you accept patches for the
source code? Note that I see why projects are doing that:
Because a Wiki has a lower barrier for entry. However, this
argument doesn't hold nowadays, given the rise of Git-powered
Wikis and similar developments.

So, what does this all have to do with our package versions?
Well, before I restructured MXE, we fulfilled the second
equation only in a loosened sense:

    documentation "is generated from" repository content

While this is quite common (and the only doable way in big
projects, using Doxygen or similar tools), we actually used
the generator "make dist" just to create the authors list
and the package list. So the index.html in the repository
was almost, but not exactly, equal to the index.html shipped
in release tarballs and on the website. That's not a big
deal, but I found this quite annoying over time. So I decided
to move the package list completely into index.html. Instead
of generating index.html from the Makefile, I parsed index.html
in the Makfile. That way I achieved the real equation

    documentation = repository content

meaning that there is no generation step involed anymore,
making it possible to always operate directly on the final
docs. It also means that every user has a full documentation
in the repository checkout, rather than just in the release
tarball (which we removed anyway since release 2.22).

Note that I also adjusted the automatic version upgrade
mechanism "make update" to make changes to index.html rather
than the *.mk files. (However, it still touches the *.mk
files to update the checksum, so this won't confuse Make.)

Thanks for reading about the backgrounds and design
decisions up to here! Now, let's get back to the problem
at hand. :-)

I'm not happy with the version numbers in index.html,
either. However, since I wanted the package version numbers
to show up on the website (and thus in the docs), it was
just logical to move them from *.mk to index.html the same
way I move the package websites and other stuff to index.html.
Although I don't want to go back to generating docs, I see
some other ways to move the version numbers back to *.mk:

1) Don't show the version numbers in the docs, providing
   a plain package list.

2) Show the version number in the package list, but generate
   it via a small JavaScript snipptet which reads and parses
   the src/*.mk files.

Note that 2) would mean we require JavaScript to be enabled
in the browser. On the other hand, there is a straight, nice
downgrade path (show everything except version numbers) for
browsers without JavaScript, so this wouldn't be much of a
limitation.

I'd love to read opinions on that, and to read other proposals
that keep the design goals in mind.


Regards,
Volker

-- 
Volker Grabsch
---<<(())>>---