[#2122] Add page dedicated to release notes.

adiroiban commented 10 years ago

Problem

This started from a comment from @alibotean that we should have ticket id in release notes.

Changes

I start updating the release notes section from Generic page and found out that release process needs a dedicated page.

For now the release process only contains info about release notes but for the future I plan to add more details about downloadables / known issues / upgrade part / public announcement.

I have updated wiki page to point to this future styleguide page https://trac.chevah.com:10443/wiki/Development/ProductRelease

I would like to slowly move to a open/public development process and this is why I have published this information on styleguide. Also, the information might be useful for other people working/starting a new project.

For now the wiki will only contain private/technical info or info which are not useful for the public audience.

How to test

reviewers: @alibotean @lgheorghiu

Read the new document and let me know if it make sense.

For now styleguide publish / build system is broken. This is why the changes are not published yet. I am working to fix it, but the text can be reviewed.

Thanks!

adiroiban commented 10 years ago

needs-review

lgheorghiu commented 10 years ago

The Release Notes we currently have are quite clean and clear, adding tags for each phrase feels like a little too much information. As you said in the description Consider the audience when writing the note. Is a ticket number useful information for the client? The ticket number might be useful for internal usage, but not exactly for the end user. The Know Issues page should have the ticket number (as this translates in we are aware of the issue, we are addressing it) Defect Fixes could use the ticket number, some of these being Known Issues from previous versions. But I don't feel like we need to add ticket number for each feature. In the end, it's a feature, not a bug :smile:

alibotean commented 10 years ago

Looks good! I'm inclined to agree with @lgheorghiu about sticking with issue/bug IDs only for Known Issues and Defects.

needs-changes

adiroiban commented 10 years ago

OK. We can except ticket ID from new features.

Beside end-users, the release notes and known issues are also used by our (non-existent) "support team" to check if a reported issue was fixed and to know in which version it was fixed.

So not only end-users are the audience for the release notes.

Since the ticket ID is not public to end users, that information is not useful at all (yet) for public users... but I think that the ticket ID is very important for the support team.

I placed the tags at the end so that users can stop/skip them. I find that at least scp/sftp/linux/aix/solaris/windows tags are very important as they help end users to identify if they are affected or not by the change.

I have also added @dumol in the loop to get feedback from a syadmin :) ... so @dumol try to review this branch as a sysadmin and not as a member of support team.

@alibotean try to review this from the point of view of support team.

Please check latest changes.

Thanks!

adiroiban commented 10 years ago

please see previous comment

needs-review

alibotean commented 10 years ago

Putting myself in the shoes of the support crew, here are my thoughts:

bugs/issues: sometime the scenario in which they manifest themselves is complex, based on certain system configuration/components versions, etc. Being able to quickly navigate to the actual bug description and fix I think will help -- based on my previous support experience.
new features: as for new features I think all the members of the support team should be well familiarized -- in advance -- with all the features that we release (and their quirks, if suitable).

Fixed some minor typos.

approved-at a6ff012

dumol commented 10 years ago

Doc changes seem sane. No nitpicking this time… :)

approved-at a6ff012

lgheorghiu commented 10 years ago

I still do not think the ticket should be added as a tag for all listings in a release note. Support team can easily use the trac milestone feature that allows to see all tickets closed against a version. For example: https://trac.chevah.com:10443/milestone/Server-2.1.0.

All internal information is at support disposal, while the documentation is for end user mainly and should be user friendly.

approved-at a6ff012

adiroiban commented 10 years ago

I also have on strong feelings for keeping ticket id in release notes.

Right now the guide is "Ticket ID marker is not required for new features."

I can change to "Ticket ID marker is only required for bug fixes and for fixing previous known issues." Is that ok?

Thanks!

lgheorghiu commented 10 years ago

No, no. It's just fine the way it is now.

chevah / geck