UX: hub pull-request strips Markdown headers

[mgedmin]

I was creating a pull request for Ansible by running hub pull-request. It downloaded Ansible's PULL_REQUEST_TEMPLATE.md very felpfully and spawned Vim for me. I edited the PR description, which looked something like

##### ISSUE TYPE
 - Bugfix Pull Request

##### COMPONENT NAME
blah blah

##### ANSIBLE VERSION
ver ver

##### SUMMARY

bug bug bug

and then I quit vim and looked at the PR that hub created for me.

I discovered that hub had stripped off all the Markdown headers, resulting in a nonsensical-looking

• Bugfix Pull Request

blah blah
ver ver
bug bug bug

This is rather unfriendly to projects that use the # header syntax in their .github/PULL_REQUEST_TEMPLATE.md.

(I was using hub version 2.3.0-pre4.)

[mislav]

This is known, but thank you for opening the issue because I feel this is something that I need to fix. The # character is the default comment character for various git messages, such as commit subject & body, but this default doesn't work as well with Markdown. Maybe hub pull-request and hub issue create should use a different default comment character.

[pirj]

@mislav I think changing the default git comment char may resolve this. hub does not seem to work with an auto setting, however, it plays nicely with core.commentchar=-.

[mgedmin]

FWIW - is often used for Markdown lists, and it'd be a shame it hub stripped those. ; sounds safer.

[pirj]

You may prefix - in lists with a space and it does not count as a comment then, but in general yes, ; is a better choice.

[jasonkarns]

Another workaround is to use ==== and ---- underlining the headers, since that is also valid markdown for headers.

A First Level Header
====================

A Second Level Header
---------------------

[cben]

I've seen some projects switch from ## in templates to ==== and ----- due to this, but not all. E.g. the OP example of Ansible wants tiny level-5 headers to can't use -----.

• hub could invoke git with different commentchar just for that command (to not mess with user settings otherwise)?
  wait, git is not used to open PRs! Does hub just emulate same behavior? If so we fully control it?

  • emulating commentchar auto could be nifty.
  • we could make the recognition stricter, recognizing a "comment string". Requiring # followed by space would avoid collisions with #123 references and ## and deeper headings. Hub could also pre-fix # headings to ## headings — not perfect but better than having them stripped...

• https://stackoverflow.com/a/2788126/239657 says prepending a single space prevents git from stripping the chars. Indeed that worked through hub, and GitHub still rendered it as header: test whitespace-prefixed markdown headers cben/sandbox#6 (also in worked in README.md). http://spec.commonmark.org/0.27/#atx-headings says "The opening # character may be indented 0-3 spaces.", this is consistent with other constructs in markdown, so can be relied upon.

  So another kludge hub could use to workaround this is prepend a space to every template line starting with commentchar.

@mislav I'll try to send a PR, if you choose desired behavior.

[mislav]

@cben commentchar=auto support is coming and there's no need to contribute anything there right now. However, auto support is not a definite solution to this problem. Supporting auto is definitely useful when there is a pull request template that has markdown headings, for instance, because a comment character such as ; would automatically be used instead of #, but in the absence of # characters in the initial PR message, you might be tempted to create a markdown heading yourself by typing one out, which wouldn't work.

I still think we should change the default comment character for these commands. The question, however, is whether we would break certain automations that people have set up using hub? 🤔

[jasonkarns]

Speaking only for myself, the scripts that I have using hub don't involve manually editing the PR message, but rely on providing PR message on the command line with -m.

[adriancooney]

Could we just strip the last four lines of the PULL_REQUEST (if they all start with #) file rather than stripping out all lines that start with the # symbol?

[anton-rudeshko]

There is also scissors cleanup mode. It is used in git commit --verbose.

Maybe it is a good fit to be used as default?

[mislav]

@anton-rudeshko That's an excellent idea. Instead of comments being stripped, everything below the cutoff line will be stripped. This will allow people to freely write Markdown in pull requests, issues, releases.

Any takers?

[anton-rudeshko]

BTW, you also can bypass this little nuisance by prefixing your MD headers with one space when you're in the hub PR description editor:

-#### Template header
+ #### Template header
 
 _template text_

As such it will not be treated as comment and will make it's way to resulting PR description.

[jonnystoten]

@mislav OK if I take a stab at this?

[mislav]

@jonnystoten By all means, please. I'd imagine that the best approach would be implementing the "scissors" mode and have it be the default.

[redreceipt]

@mislav what was the solution here? Has it been fixed?

[jonnystoten]

Thanks for the reminder @redreceipt! I've just opened a PR to fix this. ❤️

[djrodgerspryor]

Looking at the code change here it seems like there's no longer any way to add comment lines to PR templates, is that correct?

We were relying on that feature to add notes and suggestions for the PR author in our templates which didn't render in the final description itself — the new scissor syntax doesn't let us do that, because our non-rendering comments are interspersed with visible lines.

Would you be open to adding a comment syntax (which doesn't interact accidentally with markdown) or making the scissors mode switchable?

[mgedmin]

GitHub issue/PR templates usually use <!-- comments --> to tell the submitter what to do. Even if these aren't deleted by the submitter, they won't be visible in the rendered markdown.