RFR: Remove version numbering

David Holmes david.holmes at oracle.com
Tue May 26 00:58:40 UTC 2020


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.

> 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.

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
> 


More information about the guide-dev mailing list