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
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 >_______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
If a developer adds extra functionality. Is this same developer responsible for updating the ''TeX'' file? Yours Sincerely, Stefan de Konink _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
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.htmlI didn''t realise that had been written already, but now I think about it it''s not going to help anyway. regards john _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
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_______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
> 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! _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
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
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
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_______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
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 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
> 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! _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel