RFR: Remove version numbering

Wed May 27 12:20:05 UTC 2020

I don't think version numbers are any good, on the same ground that 
Jesper argues against them.

And I don't think a timestamp is a good idea, on the same ground that 
David argues against them.

If the intention here is to keep a living, correct, up to date document, 
timestamps and versions are of no use. If we change our process or 
tools, we change the document. If a specific page has not been changed 
for a long time, it just means that it is still valid, given that we 
take responsibility of keeping the entire guide up to date.

Just remove the distraction and boilerplate!

/Magnus

On 2020-05-26 19:42, Jesper Wilhelmsson wrote:
>> On 26 May 2020, at 02:58, David Holmes <david.holmes at oracle.com> wrote:
>> On 26/05/2020 10:28 am, Jesper Wilhelmsson wrote:
>>>> On 26 May 2020, at 02:01, David Holmes <david.holmes at oracle.com> wrote:
>>>>
>>>> Hi Jesper,
>>>>
>>>> On 26/05/2020 8:01 am, Jesper Wilhelmsson wrote:
>>>>> Removed release notes and version numbers from all pages. Added a footer which displays file modification date and time
>>>>> instead. The modification time is currently only placed at the bottom of each file, while the version number was
>>>>> present both at the top and at the bottom. This was made on purpose. Please leave a comment if you disagree with that
>>>>> decision. It's a simple makefile change to add it at the top as well.
>>>> Seems okay, but do we want any kind of change history in the documents themselves? I find a last modified date of little use in general.
>>> The complete change history is available in the GitHub repo: https://github.com/openjdk/guide/commits/master
>>> You can also see history for individual files: https://github.com/openjdk/guide/commits/master/src/changePlanning.md
>> Sure but I don't expect people to have to go to the repo to check the history. Version numbers indicate relative significance of changes, so if discussing something and you have version 2 while someone else references version 3, then you know you have to update and see what changed. Without a version number there is no direct indication of any significant changes. A change history captures that as part of the visible document.
> I'm not sure why the average reader would care about the history of this document at all. They just want to find the answer to their current question and have presumably little interest in knowing how that question was answered in the past. The change history is of more importance to maintainers of the guide, and as such I would expect people to go to the repo.
>
> The version number as it looks right now has both a major and a minor part. Deciding if a change is major or not is a difficult task, and may be cause for friction within the project if someone think they did a huge job while others don't see the importance of that work. Where do we draw the line between a major change and a minor change? This is especially difficult in a living document where many small changes are expected frequently, and the major change might evolve through many smaller changes. It's basically the same problem as with the JEP process - If a number of smaller changes over several releases turns out to sum up to a new feature - would the last small change get a JEP?
>
>>> Adding the date was suggested in a previous thread. To me it serves as a way to at least get an impression of how current some information is. In this case it also serves as a tag on the document to refer to in discussions where the version number was previously used. Since the date is kept up to date automatically it's a more convenient way to tag the document.
>> I find such a date of little use because the bulk of the content could be 10 years old and out of date, but a recent insignificant edit (maybe a broken URL) caused the last modified date to be updated. Such a single value really tells you nothing about how current the information is.
> This is clearly the case right now as we just started to update the guide after many years, but I do hope that we manage to get this up to date and keep it up to date. If not this project would need more attention. So if we assume that a page has information that is a few years old but which is still up to date, and that page is updated to fix a broken link, the updated date could be seen as an indication that the page is alive and has been verified to still be up to date. I know it's impossible to tell the difference, but in the end I guess it's about how much trust one has in the maintainers of the guide. That's something I and others will have to work on earning.
>
> For the version number to be a trustworthy reference in discussions and references to the guide, it basically has to be updated for every "release". As we don't have scheduled releases, and I really hope to update the online document as frequently as we make changes in the repo, this would be quite often. Even though the effort of updating the version number could be reduced (it's currently hard-coded in two places on every page) by using a similar header/footer as I introduce in this change, there would still be a manual task required for every release. I envision this to become one of those "you forgot to update the copyright header"-type of issues :-)
>
> Also, in the end I really hope that no-one (except maintainers of course) will have their own local copy of the guide. It's an online document and it's not distributed in any bundles or release artifacts. So the value of both a version number and a date is in my opinion very limited. But having the date adds value to some and it requires no maintenance, so I don't see any harm in adding it.
>
> ��
> /Jesper
>
>> Cheers,
>> David
>>
>>> /Jesper
>>>> Thanks,
>>>> David
>>>>
>>>>> -------------
>>>>> Commit messages:
>>>>>   - Remove version numbering
>>>>> Changes: https://git.openjdk.java.net/guide/pull/9/files
>>>>>   Webrev: https://webrevs.openjdk.java.net/guide/9/webrev.00
>>>>>    Stats: 158 lines in 20 files changed: 5 ins; 152 del; 1 mod
>>>>>    Patch: https://git.openjdk.java.net/guide/pull/9.diff
>>>>>    Fetch: git fetch https://git.openjdk.java.net/guide pull/9/head:pull/9
>>>>> PR: https://git.openjdk.java.net/guide/pull/9