Closed ezio-melotti closed 2 years ago
- Import messages within code-block markup, to render it literally:
One nice aspect of this is that bpo issues are currently displayed monospace. Without adequate conversion of code blocks such as in (3), code snippets and places where alignment is important would look broken. (3) seems quite hard to implement though, a lot of the formatting is ad-hoc (I know I've personally sometimes kept code blocks on the same level or indented them with 2 or 4 spaces occasionally). It seems like (1) might be the way to go. If we really want (2) there are mature libraries like turndown.
On bpo, links to other issues, messages, PRs, PEPs, etc. are added at rendering time using regexes.
This is probably less of a concern with https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/configuring-autolinks-to-reference-external-resources which we already have set up for bpo links on the CPython repo thanks to @mariatta in https://github.com/python/core-workflow/issues/361
Issues numbers can also be remapped from the bpo to the GH numbers during the same step.
Depending on the resolution to #2, it might be nice to keep the links the same and then the bugs.python.org/issuexxx
links end up redirecting you to the right Github page. But assuming we make the roundup instances read-only or mirrored then remapping the issues is probably a good idea.
We have:
We want:
It seems that:
or ```...``` can be used to show the code in a monospaced block:
the background looks different and
explicit links like https://bugs.python.org/issue2771 are not clickable
this also doesn't work [these](https://bugs.python.org/issue2771#msg154050)
and neither does #3
If we want to implement option 2 from the first message, we could:
If we want to implement option 3, we could parse each paragraph independently and:
py
by default for all blocks>>>
/ keywords like def
) to detect Python, use text
otherwisetext
I'll do some tests on a real world sample to see if we can reach a good compromise.
This issue is about converting and formatting the content (text) of the bpo messages (not the issue metadata) before importing them into GitHub.
bpo messages are raw text with no formatting, whereas GitHub issues use Markdown. If messages are imported directly, special characters in the bpo messages might be wrongly interpreted as Markdown formatting, resulting in erroneous rendering.
Possible solutions:
Edit: I went with option 3. It's not perfect, but it seems to work well enough.
Other considerations:
#XXXX
,issueXXXX
,issue XXXX
refs should be replaced bybpo-XXXX
and possibly replaced after the migrationmsgXXXX
andmsg XXXX
could be converted to markdown links to the corresponding bpo issue.fileXXXX
andfile XXXX
are not used frequently and could be ignoredPEP xxx
toPEP-xxx
or the autolinking won't work0
s also break the link (see python/peps#2420)GHXXXX
,GH XXXX
,PRXXXX
,PR XXXX
,pull request XXXX
,BPOXXXX
,BPO XXXX
should all be hyphenated or the autolinking won't workrXXXXX
) link tohttps://hg.python.org/lookup/rXXXXX
but are currently brokenLib/somefile.py
,Modules/somemodule.c
,Doc/somedocfile.rst
) can be converted to markdown links#xxxx
during the transfer but only for issues that have been transferred alreadybpo-xxxx
prevents rewrite and can use the bpo redirect added in #17TODO: