Bug 54239 - [Release notes] Starting with Xamarin.iOS 9.6, top heading in the release notes no longer includes the version number
Summary: [Release notes] Starting with Xamarin.iOS 9.6, top heading in the release not...
Status: RESOLVED ANSWERED
Alias: None
Product: iOS
Classification: Xamarin
Component: General ()
Version: XI 10.8 (d15-1)
Hardware: PC All
: --- minor
Target Milestone: Future Cycle (TBD)
Assignee: Adrian Murphy
URL:
Depends on:
Blocks:
 
Reported: 2017-03-29 18:45 UTC by Brendan Zagaeski (Xamarin Team, assistant)
Modified: 2017-05-18 15:05 UTC (History)
4 users (show)

Tags:
Is this bug a regression?: ---
Last known good build:


Attachments
Screenshot of the LESS PRECISE heading on the Xamarin.iOS 9.6 release notes (98.67 KB, image/png)
2017-03-29 18:45 UTC, Brendan Zagaeski (Xamarin Team, assistant)
Details
Screenshot of the MORE PRECISE heading on the Xamarin.iOS 9.4 release notes (108.32 KB, image/png)
2017-03-29 18:46 UTC, Brendan Zagaeski (Xamarin Team, assistant)
Details


Notice (2018-05-24): bugzilla.xamarin.com is now in read-only mode.

Please join us on Visual Studio Developer Community and in the Xamarin and Mono organizations on GitHub to continue tracking issues. Bugzilla will remain available for reference in read-only mode. We will continue to work on open Bugzilla bugs, copy them to the new locations as needed for follow-up, and add the new items under Related Links.

Our sincere thanks to everyone who has contributed on this bug tracker over the years. Thanks also for your understanding as we make these adjustments and improvements for the future.


Please create a new report on Developer Community or GitHub with your current version information, steps to reproduce, and relevant error messages or log files if you are hitting an issue that looks similar to this resolved bug and you do not yet see a matching new report.

Related Links:
Status:
RESOLVED ANSWERED

Description Brendan Zagaeski (Xamarin Team, assistant) 2017-03-29 18:45:23 UTC
Created attachment 21026 [details]
Screenshot of the LESS PRECISE heading on the Xamarin.iOS 9.6 release notes

[Release notes] Starting with Xamarin.iOS 9.6, top heading in the release notes no longer includes the version number




## GOOD heading for Xamarin.iOS 9.4 and lower

On the Xamarin.iOS 9.4 release notes [1], the top heading of the page is:

> Xamarin.iOS 9.4

[1] https://developer.xamarin.com/releases/ios/xamarin.ios_9/xamarin.ios_9.4/




## LESS PRECISE heading for Xamarin.iOS 9.6 and higher

On the Xamarin.iOS 9.7 release notes [2] and higher, the top heading of the page no longer includes the version number:

> Xamarin.iOS

[2] https://developer.xamarin.com/releases/ios/xamarin.ios_9/xamarin.ios_9.6/




## Possible improvements

If this change was unintentional, then perhaps for upcoming releases the version number can be included at the end of the `title:` metadata item.

If the change was _intentional_, then this bug report can be resolved as "feature", ideally with a brief explanation of the reason.  Thanks!
Comment 1 Brendan Zagaeski (Xamarin Team, assistant) 2017-03-29 18:46:10 UTC
Created attachment 21027 [details]
Screenshot of the MORE PRECISE heading on the Xamarin.iOS 9.4 release notes
Comment 2 Sebastien Pouliot 2017-03-30 12:52:35 UTC
This happened when switching the from our old custom html-based file format we used to the new markdown-based template provided by Adrian, where `title` and `version` are split entries.

@Adrian ?
Comment 3 Vincent Dondain [MSFT] 2017-05-18 10:04:56 UTC
Indeed the template we use for release notes changed between 9.4 and 9.6 when moving to markdown.

@adrian was it explicitly defined when you created the new release notes template to *not* put the exact version number in the title anymore? (for style reasons).

However I'm not sure it's wanted given that other products keep putting the version number in their title: https://developer.xamarin.com/releases/android/xamarin.android_7/xamarin.android_7.3, https://developer.xamarin.com/releases/studio/xamarin.studio_6.3/xamarin.studio_6.3,
https://developer.xamarin.com/releases/interactive/interactive-1.3
etc...

Either we're doing it right and all the others are wrong or the other way around.

I personally think that for extra clarity, the title should have the version number (even though it's what you select on the right hand side menu). It makes it clearer when moving between XI release notes.
Comment 4 Adrian Murphy 2017-05-18 15:03:28 UTC
ultimately the product leads own the notes so it's up to you guys
if you want to add versioning back in feel free
Comment 5 Vincent Dondain [MSFT] 2017-05-18 15:05:06 UTC
Ok so it's your call @sebastien but as I said we might want to update our release notes (and the future ones) for coherence with other products and with our old notes (pre 9.4).