Better handling of ChangeLog style commit messages

[Mikael Hallendal]

It's pretty common and useful to paste the ChangeLog message as the commit log message. Would be nice if the timeline view could show this message nicely "tagged". For example

               * src/foo.c: oaiwjefoiewajf
               - woaifjowijf

Could keep a link to the svn:/src/foo.c and format the text nicely.

Any thoughts?

[daniel]

See also #352.

[oohlaf@…]

Currently a - or + isn't recognised as second or third level. Ticket #352 does add newlines so it makes it a bit more readable, but thats not the same as a nested level.

 * One
   - Two
     + Three

Or some people prefer:

 * One
   + Two
     - Three

The GNU coding standard of change logs is to put the modified filename first followed by a colon and can happen at every level. Sometimes it contains the changed functions in parantheses.

Problem is that Trac does not know in which directory the file is. It could parse the set of changed files from the changeset and use the biggest match.

2002-07-14  John Doe  <jdoe@gnu.org>
 * sew.c (sew, main): Make it sew. Patch by charly@sew.me.com.

So if the changeset contains a modified/added file trunk/project/src/sew.c it could contain a link to the source browser.

There are a lot of projects who follow the GNU coding style (some because of historic reasons).

[cboos]

Since [1561], changelog-style commit messages should be correctly formatted. However, automatically adding links for filenames is still an open issue.

[cboos]

However, automatically adding links for filenames is still an open issue.

That should be tracked in #1200.

[cboos]

I'd like to reopen this one, as I think I've come with an improved way to handle the wiki lists, which is more robust and as a side-effect handles the usual Changelog styles much better.

A few examples:

1. Deeply indented list (using spaces)

The text

Thu Apr 20 00:53:28 PDT 2006  Christian Hammond <chipx86@chipx86.com>

	* NEWS:
	  - Add the release datestamp.

Mon Apr 17 01:00:21 PDT 2006  Christian Hammond <chipx86@chipx86.com>

	* src/galago.defs:
	  - Remove the {set,get}_exit_with_daemon() wrappers.

Mon Apr 17 00:25:01 PDT 2006  Christian Hammond <chipx86@chipx86.com>

	* NEWS:
	* configure.ac:
	  - Bump the version to 0.5.0.
	  - Update the copyrights.

will be rendered like this:

---

Thu Apr 20 00:53:28 PDT 2006 Christian Hammond <chipx86@chipx86.com>

• NEWS:
  • Add the release datestamp.

Mon Apr 17 01:00:21 PDT 2006 Christian Hammond <chipx86@chipx86.com>

• src/galago.defs:
  • Remove the {set,get}_exit_with_daemon() wrappers.

Mon Apr 17 00:25:01 PDT 2006 Christian Hammond <chipx86@chipx86.com>

• NEWS:
• configure.ac:
  • Bump the version to 0.5.0.
  • Update the copyrights.

---

instead of:

---

Thu Apr 20 00:53:28 PDT 2006 Christian Hammond <chipx86@…>

• NEWS:
  • Add the release datestamp.

Mon Apr 17 01:00:21 PDT 2006 Christian Hammond <chipx86@…>

• src/galago.defs:
  • Remove the {set,get}_exit_with_daemon() wrappers.

Mon Apr 17 00:25:01 PDT 2006 Christian Hammond <chipx86@…>

• NEWS:
• configure.ac:
  • Bump the version to 0.5.0.
  • Update the copyrights.

---

2. Tab indented list, direct continuation

The text:

2003-09-18 23:26  Chris Hanson <cph@zurich.ai.mit.edu>

	* imail/imail-imap.scm (1.200): Fix problem with obsolete use of
	backslash in symbols.

2003-09-18 20:39  Chris Hanson <cph@zurich.ai.mit.edu>

	* runtime/: random.scm (14.30), runtime.pkg (14.457): Implement
	external representation for random-state objects.

will be rendered like this:

---

2003-09-18 23:26 Chris Hanson <cph@zurich.ai.mit.edu>

• imail/imail-imap.scm (1.200): Fix problem with obsolete use of backslash in symbols.

2003-09-18 20:39 Chris Hanson <cph@zurich.ai.mit.edu>

• runtime/: random.scm (14.30), runtime.pkg (14.457): Implement external representation for random-state objects.

---

instead of:

---

2003-09-18 23:26 Chris Hanson <cph@…>

• imail/imail-imap.scm (1.200): Fix problem with obsolete use of backslash in symbols.

2003-09-18 20:39 Chris Hanson <cph@…>

• runtime/: random.scm (14.30), runtime.pkg (14.457): Implement external representation for random-state objects.

---

The attachement:robust_lists_r3271.diff provide the necessary changes. Surprisingly, all the existing unit tests still pass :)

[cboos]

That was not really apparent in the above example, as they both were using tabs for indenting instead of space, but the patch actually fixes lists which start at an arbitrary depth:

               * src/foo.c: oaiwjefoiewajf
                - woaifjowijf

would be rendered as:

---

• src/foo.c: oaiwjefoiewajf
  • woaifjowijf

---

instead of:

---

• src/foo.c: oaiwjefoiewajf
  • woaifjowijf

---

[cboos]

Refactor the list formatter

[cboos]

As discussed with Alec on IRC, I've added the same logic for blockquotes than the one I used for lists, i.e. each increase in indentation will create only one additional block level.

Also, this introduces support for a citation syntax, which reuses most of the indentation code.

A wiki text like:

----
alpha wrote:
> beta wrote:
>> what about being able to add reply to comment?
> I'd like this!
So let's implement it...
----

will be rendered like this:

---

alpha wrote:

beta wrote:

what about being able to add reply to comment?

I'd like this!

So let's implement it...

---

Plus there's normally a bit of CSS which makes the above output look prettier (no margins and a solid left border).

Even more surprisingly than before, all the existing tests still passes :)

[cboos]

In addition to the previous improvements to the lists, this features improvements for the quotation blocks. Diff on trunk@3278. Take 3

[cboos]

Above patch refined and committed in r3317. Further modifications done in r3318 to restore the implicit coupling between lists and quotes indentations.

I took a lot of various source changelog texts from the net, and tried to render them with the above code, and I'm quite satisfied with the results.

However, don't hesitate to open new tickets if there's still some situations where the rendering of lists and quotes doesn't seem intuitive.

[cboos]

(and the citation syntax present in the patch was introduced in a separate changeset, r3320)

[cboos]

Hm, one last possible enhancement on this topic would be to start bulleted lists even if there's no space in front of the bullet...

* Fixed this
* And that

or (from [ps260]):

- Remove unused files.
- More error checks.
- More inline comments and docstrings.
- ...

But that might break paragraphs with lines starting with a * or -, though that's probably not that common and can be easily fixed.

[eblot]

I don't think the "bullet without indentation" thing is a good idea.

It would be nice for Changelogs, but it does not fit well in regular wiki pages, where natural language presentation trends to use a list of enumerated items below a description of the list.

Wiki syntax should be consistent in both wiki pages and changelog.

If you implement such a change, please make it optionnal so that the "item without a list description" can be disabled.

[cboos]

I don't understand your point: it would still be possible to have "a list of enumerated items below a description of the list."

With the proposal, you would write:

All my items:
- item 1
- item 2 

and of course, the old way would still work:

All my items:
 - item 1
 - item 2

Maybe you should show me a counter example .

[cboos]

#1936 was marked as duplicate.

Also, note that in the above comments, the "instead of" sections are now rendered identically to the "would be rendered as:" sections, as this Trac is now running the new code...