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