Remove version numbering #9
Conversation
|
👋 Welcome back jwilhelm! A progress list of the required criteria for merging this PR into |
|
Mailing list message from David Holmes on guide-dev: Hi Jesper, On 26/05/2020 8:01 am, Jesper Wilhelmsson wrote:
Seems okay, but do we want any kind of change history in the documents Thanks, |
|
Mailing list message from Jesper Wilhelmsson on guide-dev:
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 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. /Jesper
|
|
Mailing list message from David Holmes on guide-dev: On 26/05/2020 10:28 am, Jesper Wilhelmsson wrote:
Sure but I don't expect people to have to go to the repo to check the
I find such a date of little use because the bulk of the content could Cheers,
|
|
Mailing list message from Jesper Wilhelmsson on guide-dev:
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?
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. ??
|
|
@JesperIRL This change now passes all automated pre-integration checks, type
There are currently no new commits on the ➡️ To integrate this PR with the above commit message to the |
|
Mailing list message from Magnus Ihse Bursie on guide-dev: I don't think version numbers are any good, on the same ground that And I don't think a timestamp is a good idea, on the same ground that If the intention here is to keep a living, correct, up to date document, Just remove the distraction and boilerplate! /Magnus On 2020-05-26 19:42, Jesper Wilhelmsson wrote:
|
Reviewed-by: iris
Reviewed-by: iris
Reviewed-by: iris
|
@JesperIRL this pull request can not be integrated into git checkout updates
git fetch https://git.openjdk.java.net/guide master
git merge FETCH_HEAD
# resolve conflicts and follow the instructions given by git merge
git commit -m "Merge master"
git push |
|
Since there is reluctance to add the date to the files I have updated the patch. The original discussion that lead to adding the date actually suggested adding the date or the change hash of each file. This new patch adds the change hash instead. It also adds a link to the change history for each file. |
|
Mailing list message from David Holmes on guide-dev: On 28/05/2020 2:29 pm, Jesper Wilhelmsson wrote:
I think this is a good compromise. Thanks, |
|
/integrate |
|
@JesperIRL |
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.
Progress
Reviewers
Download
$ git fetch https://git.openjdk.java.net/guide pull/9/head:pull/9$ git checkout pull/9