API Changelog

API Changelog

[John Levon]

Now I remember why I didn't want a file in the source tree. There's
absolutely no sensible way to have any entries there that give a
meaningful link to the actual details - you can't link to the rev until
it's merged, and you can't commit until the rev is written in it.

The only other option is dates which is way too vague (date when the
patch was written is a really poor indicator of when the change got
merged).

I guess keywords would help, except mercurial doesn't do them. Keir?

regards
john

Re: API Changelog

[Ben Guthro]

It does via an extension:
http://www.selenic.com/mercurial/wiki/index.cgi/KeywordExpansionExtension
http://osdir.com/ml/os.solaris.opensolaris.tools.general/2006-05/msg00167.html

John Levon wrote:
> Now I remember why I didn't want a file in the source tree. There's
> absolutely no sensible way to have any entries there that give a
> meaningful link to the actual details - you can't link to the rev until
> it's merged, and you can't commit until the rev is written in it.
>
> The only other option is dates which is way too vague (date when the
> patch was written is a really poor indicator of when the change got
> merged).
>
> I guess keywords would help, except mercurial doesn't do them. Keir?
>
> regards
> john
>
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xensource.com
> http://lists.xensource.com/xen-devel
>   

Re: API Changelog

[John Levon]

On Mon, Jan 07, 2008 at 11:30:28AM -0500, Ben Guthro wrote:

> It does via an extension:
> http://www.selenic.com/mercurial/wiki/index.cgi/KeywordExpansionExtension
> http://osdir.com/ml/os.solaris.opensolaris.tools.general/2006-05/msg00167.html

I didn't realise that had been written already, but now I think about it
it's not going to help anyway.

regards
john

Re: API Changelog [new functionality]

[Stefan de Konink]

If a developer adds extra functionality. Is this same developer 
responsible for updating the 'TeX' file?


Yours Sincerely,

Stefan de Konink

Re: API Changelog [new functionality]

[Ian Jackson]

Stefan de Konink writes ("Re: [Xen-devel] API Changelog [new functionality]"):
> If a developer adds extra functionality. Is this same developer 
> responsible for updating the 'TeX' file?

Certainly if you have a substantial change, or one which introduces
new APIs then I think you should submit documentation of some kind in
the same patch.

However the tex document is currently badly out of date, and
annotating documentation contributions to turn them into typesettable
TeX is an unneeded distraction.  I think traditional 70ish-column
ASCII plain text is a better format for our internal documentation -
for example, see the recently added xenstore protocol document and the
API changelog.

So if when you submit a patch you include a corresponding change to
the tex document I think we would be happy to accept that, but I think
we should be aiming to move towards plain text documents which we can
expect people to keep current.

So I would suggest including documentation for your change as text in
the docs/ directory - either as new files or modifications to existing
files as appropriate.  Include an entry in docs/ChangeLog if there are
ABI changes.

Ian.

Re: API Changelog [new functionality]

[Ian Jackson]

I wrote ("Re: [Xen-devel] API Changelog [new functionality]"):
> So I would suggest including documentation for your change as text in
> the docs/ directory - either as new files or modifications to existing
> files as appropriate.  Include an entry in docs/ChangeLog if there are
> ABI changes.

Also, of course, if there are changes to interfaces which are defined
and documented in the public header files, the relevant comments and
definitions there should be changed.  That's less easy to overlook,
though.  In general better cross-referencing between docs/ and
xen/include/public/ might help too.

So I don't think we should aim for a revolution overnight, but if we
try to ensure that we gradually make things better in a while we'll
have a more sane and better-documented system·

Ian.

Re: API Changelog [new functionality]

[Keir Fraser]

Yes, plain text is the way to go, especially for developer documentation.

  --  Keir

On 8/1/08 16:54, "Ian Jackson" <Ian.Jackson@eu.citrix.com> wrote:

> Stefan de Konink writes ("Re: [Xen-devel] API Changelog [new functionality]"):
>> If a developer adds extra functionality. Is this same developer
>> responsible for updating the 'TeX' file?
> 
> Certainly if you have a substantial change, or one which introduces
> new APIs then I think you should submit documentation of some kind in
> the same patch.
> 
> However the tex document is currently badly out of date, and
> annotating documentation contributions to turn them into typesettable
> TeX is an unneeded distraction.  I think traditional 70ish-column
> ASCII plain text is a better format for our internal documentation -
> for example, see the recently added xenstore protocol document and the
> API changelog.
> 
> So if when you submit a patch you include a corresponding change to
> the tex document I think we would be happy to accept that, but I think
> we should be aiming to move towards plain text documents which we can
> expect people to keep current.
> 
> So I would suggest including documentation for your change as text in
> the docs/ directory - either as new files or modifications to existing
> files as appropriate.  Include an entry in docs/ChangeLog if there are
> ABI changes.
> 
> Ian.
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xensource.com
> http://lists.xensource.com/xen-devel

Re: API Changelog [new functionality]

[Stefan de Konink]

Keir Fraser schreef:
> Yes, plain text is the way to go, especially for developer documentation.

I love to text, and actually I kinda like the look with the tables in 
the document ;)


Stefan

Re: API Changelog

[Keir Fraser]

View the file with 'hg annotate'?

 -- Keir

On 7/1/08 16:22, "John Levon" <levon@movementarian.org> wrote:

> 
> Now I remember why I didn't want a file in the source tree. There's
> absolutely no sensible way to have any entries there that give a
> meaningful link to the actual details - you can't link to the rev until
> it's merged, and you can't commit until the rev is written in it.
> 
> The only other option is dates which is way too vague (date when the
> patch was written is a really poor indicator of when the change got
> merged).
> 
> I guess keywords would help, except mercurial doesn't do them. Keir?
> 
> regards
> john

Re: API Changelog

[Mark Williamson]

> Now I remember why I didn't want a file in the source tree. There's
> absolutely no sensible way to have any entries there that give a
> meaningful link to the actual details - you can't link to the rev until
> it's merged, and you can't commit until the rev is written in it.
>
> The only other option is dates which is way too vague (date when the
> patch was written is a really poor indicator of when the change got
> merged).
>
> I guess keywords would help, except mercurial doesn't do them. Keir?

How about just including the changelog entry as a separate commit?  That way 
the commit ID of the real change can be recorded accurately.

The developer would generate the patch series using hg export - which they 
probably use already.  All that's needed at the other end is to apply the 
patch using hg import so that the commits keep the proper changeset IDs.

Another reason hg import is handy is that the developer who sent the patch 
won't get a conflict the next time they hg pull mainline.

Cheeres,
Mark

-- 
Dave: Just a question. What use is a unicyle with no seat?  And no pedals!
Mark: To answer a question with a question: What use is a skateboard?
Dave: Skateboards have wheels.
Mark: My wheel has a wheel!

Re: API Changelog

[Ian Jackson]

John Levon writes ("[Xen-devel] API Changelog"):
> Now I remember why I didn't want a file in the source tree. There's
> absolutely no sensible way to have any entries there that give a
> meaningful link to the actual details - you can't link to the rev until
> it's merged, and you can't commit until the rev is written in it.

I think  hg ann -cnaud  answers that problem quite well,
as Keir points out.

Mark Williamson writes ("Re: [Xen-devel] API Changelog"):
> How about just including the changelog entry as a separate commit?  That way 
> the commit ID of the real change can be recorded accurately.

Oh dear, please no.  That will involve manual pratting about (which
will therefore go wrong) when we have a useable automatic system for
this.  If we abolutely have to we could use some kind of keyword
expansion annotation system but personally I think that's a waste of
effort when hg ann is quite adequate.

> The developer would generate the patch series using hg export - which they 
> probably use already.  All that's needed at the other end is to apply the 
> patch using hg import so that the commits keep the proper changeset IDs.
> 
> Another reason hg import is handy is that the developer who sent the patch 
> won't get a conflict the next time they hg pull mainline.

These are orthogonal questions, I think.

Ian.

Re: API Changelog

[Mark Williamson]

> I think  hg ann -cnaud  answers that problem quite well,
> as Keir points out.

It's a shame not to have the commit IDs in plain text in the ChangeLog itself, 
but probably not a big deal, agreed.  Although isn't that slightly brittle to 
subsequent bad edits / merges obscuring the original changeset ID?

> Mark Williamson writes ("Re: [Xen-devel] API Changelog"):
> > How about just including the changelog entry as a separate commit?  That
> > way the commit ID of the real change can be recorded accurately.
>
> Oh dear, please no.  That will involve manual pratting about (which
> will therefore go wrong) when we have a useable automatic system for
> this.

I'm not clear how much manual "pratting" you think this adds...  As far as I 
can tell the only additional maintainer work required is to type "hg import" 
instead of "patch" to correctly preserve the changeset numbers.

> > The developer would generate the patch series using hg export - which
> > they probably use already.  All that's needed at the other end is to
> > apply the patch using hg import so that the commits keep the proper
> > changeset IDs.
> >
> > Another reason hg import is handy is that the developer who sent the
> > patch won't get a conflict the next time they hg pull mainline.
>
> These are orthogonal questions, I think.

It's not entirely orthogonal because it's a prereq for what I suggested: 
requesting external that developers include a changeset ID would require that 
we actually preserve that changeset ID!  Otherwise the maintainer would have 
to edit ChangeLog themself, which wouldn't fly.  Reducing disruption to 
subsequent workflow is just gravy ;-)

Cheers,
Mark

-- 
Dave: Just a question. What use is a unicyle with no seat?  And no pedals!
Mark: To answer a question with a question: What use is a skateboard?
Dave: Skateboards have wheels.
Mark: My wheel has a wheel!