[Trac-dev] ApiChanges document

[RjOllos]

At the conclusion of each milestone I've been copying the ApiChanges (1)
page forward, e.g. HEAD revision of 1.1.3 to create 1.1.4. I'm not sure
what was intended originally, but I didn't want to try and piece together a
1.2 page from 1.1.1, 1.1.2, ..., and that would be needed if each 1.1.x
ApiChanges page only contained changes for that milestone.

What results is a series of pages with a lot of duplicated content. Peter
added the version for each new interface (2). That has me thinking that it
might be better to prepare a single page for the next series of development
releases, name it 1.3.x and note the milestone in which each item was
added, removed or changed.

I'm seeking feedback on what the developers think will be easiest to
maintain, and what the consumers of the ApiChanges documentation think will
be easiest to read.

Thanks,
- Ryan

(1) http://trac.edgewall.org/wiki/TracDev/ApiChanges
(2) http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.4#NewInterfaces

[Peter Suter]

I didn't want to try and piece together a 1.2 page from 1.1.1, 1.1.2,
..., and that would be needed if each 1.1.x ApiChanges page only
contained changes for that milestone.
What results is a series of pages with a lot of duplicated content.
Peter added the version for each new interface (2). That has me
thinking that it might be better to prepare a single page for the next
series of development releases, name it 1.3.x and note the milestone
in which each item was added, removed or changed.

Duplicating the content from previous 1.1.x releases seems quite
confusing to me. (Especially as the title is "changes since 1.1.3".) But
I can see your point about wanting the full set of changes for 1.2.
A single 1.3.x page where each item mentions the milestone sounds like
an acceptable compromise to me. I'd probably also merge the current
1.1.x pages.

Thanks for bringing this up.

Peter

[Ryan Ollos]

I'd probably also merge the current 1.1.x pages.

Thanks, I'll do this in a few days if no one objects, after double-checking
that all of the documentation from earlier releases in now contained in
ApiChanges/1.1.5.

[RjOllos]

Post by Ryan Ollos

I'd probably also merge the current 1.1.x pages.

Thanks, I'll do this in a few days if no one objects, after
double-checking that all of the documentation from earlier releases in now
contained in ApiChanges/1.1.5.

I thought about it some more. We could:
* Have an ApiChanges/1.1 page with annotations showing the 1.1.x release
in which a change was made.
* Remove the 1.1.x annotations when preparing ApiChanges/1.2.

The result is two pages with distinct information. ApiChanges/1.1 page is
easy to create because it can be edited incrementally as tickets are closed
out. ApiChanges/1.2 is easy to create because the only necessary steps are
copying 1.1 and deleting some content. That can easily be done just prior
to the 1.2 release.

[Peter Suter]

Post by RjOllos
* Have an ApiChanges/1.1 page with annotations showing the 1.1.x
release in which a change was made.
* Remove the 1.1.x annotations when preparing ApiChanges/1.2.
The result is two pages with distinct information. ApiChanges/1.1 page
is easy to create because it can be edited incrementally as tickets
are closed out. ApiChanges/1.2 is easy to create because the only
necessary steps are copying 1.1 and deleting some content. That can
easily be done just prior to the 1.2 release.

I created ApiChanges/1.1, merging ApiChanges/1.1.1 to 1.1.5 and adding
version annotations.
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1

We could delete these pages now:
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.1
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.2
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.3
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.4
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.5

Or maybe better just replace them with a redirection link to 1.1.

[Ryan Ollos]

Post by RjOllos
* Have an ApiChanges/1.1 page with annotations showing the 1.1.x release
in which a change was made.
* Remove the 1.1.x annotations when preparing ApiChanges/1.2.
The result is two pages with distinct information. ApiChanges/1.1 page
is easy to create because it can be edited incrementally as tickets are
closed out. ApiChanges/1.2 is easy to create because the only necessary
steps are copying 1.1 and deleting some content. That can easily be done
just prior to the 1.2 release.
I created ApiChanges/1.1, merging ApiChanges/1.1.1 to 1.1.5 and adding
version annotations.
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.1
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.2
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.3
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.4
http://trac.edgewall.org/wiki/TracDev/ApiChanges/1.1.5
Or maybe better just replace them with a redirection link to 1.1.

Thanks for taking care of that. I'm okay with deleting the pages, but if we
want to be more conservative we could leave them with the redirect until
1.2 is released, deleting them in about 6 months.

- Ryan