Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add ability to generate Markdown "todo" list for GitHub/GitLab issues, Kanban boards, etc. #2094

Open
david-a-wheeler opened this issue Jan 8, 2024 · 26 comments
Open

Add ability to generate Markdown "todo" list for GitHub/GitLab issues, Kanban boards, etc. #2094

david-a-wheeler opened this issue Jan 8, 2024 · 26 comments

Comments

@david-a-wheeler
Copy link
Collaborator

We want people to merge "get a badge" into their wider workflows.

Add ability to generate Markdown "todo" list for GitHub/GitLab issues, Kanban boards, etc. Then the badge requirements can be easily merged into larger workflows.
@david-a-wheeler
Copy link
Collaborator Author

Maybe generate CSV for what's to do as well.

@lucasgonze lucasgonze mentioned this issue Jan 8, 2024
Closed
@david-a-wheeler david-a-wheeler mentioned this issue Jan 18, 2024
Closed
@lucasgonze
Copy link

lucasgonze commented Jan 26, 2024 •
edited

Requirements for the project:

  • There should be roughly equivalent functionality for every feature in the web app. We should attempt to be comprehensive. Omissions should be unavoidable.
  • The state of the web app should be reflected in the markdown. If an item is Met in the web app it should be checked off in the Markdown.
  • There should not be a feature to import from markdown back to the web app. There is no practical way.

Documentation on markdown for task lists:
https://github.github.com/gfm/#task-list-items-extension-

image

A useful feature is that task lists can be nested.
image

  • The "show details" documentation should be made available in the markdown as a tooltip (because markdown allows HTML).

Markdown:
The project MUST provide basic documentation for the software produced by the project. ([documentation_basics](/uri "This documentation must be in some media (such as text or video) that includes: how to install it, how to start it, how to use it (possibly with a tutorial using examples), and how to use it securely (e.g., what to do and what not to do) if that is an appropriate topic for the software. The security documentation need not be long. The project MAY use hypertext links to non-project material as documentation. If the project does not produce software, choose 'not applicable' (N/A)."))

Rendered:
image

  • Panels in the web app can be represented as nested task lists

HTML:
image

Markdown:

- [ ] Documentation
  - [ ]  The project MUST provide basic documentation for the software produced by the project. (documentation_basics) 
  - [ ]   The project MUST provide reference documentation that describes the external interface (both input and output) of the software produced by the project. (documentation_interface)

Rendered:
image

Badge criteria may be in three states: not yet researched, met, and not met.

image

We will represent those states with the following markdown:

 - [?] indeterminate 
 - [ ] not met
 - [x] met

The appearance of those is as follows:
image

The inconsistent appearance of the indeterminate state is unfortunate! You can’t make a checkbox indeterminate through HTML.

@SecurityCRob
Copy link

We discussed today in the BEST WG. The group was positive on the suggestion. David W. was going to explore more. Thanks for sharing!

@david-a-wheeler
Copy link
Collaborator Author

GitLab Flavored Markdown is defined at https://docs.gitlab.com/ee/user/markdown.html and it appears to include GitHub Flavored Markdown, which is great.

GitHub AND GitLab support:

  • Not done
  • Done

GitLab also supports this, but GitHub does not, so I think we should not use it:

  • [~] Not applicable

@david-a-wheeler
Copy link
Collaborator Author

It looks like the simplest option is to map "Met" and "N/A" to [x] and map "Unmet" and "?" to [ ].

@lucasgonze
Copy link

Notes from BEST WG Jan 30, 2024

Requirements

  • Export must be supported by github

Verify:

  • Compatibility with Pandoc, Commonmark, Gitlab, and Jira

Documentation:

Engineering:

  • ? can be mapped to "Not met" state
  • N/A can be mapped to "Met" state (Gitlab has tilde: - [~] Inapplicable task)
  • The Best Practices web app already supports an extension on the URL. Append .json or .csv to set export format. As the entry point to this exporter, consider .md extension.

@david-a-wheeler
Copy link
Collaborator Author

It's not complete, but here's a partial start: #2104

@david-a-wheeler
Copy link
Collaborator Author

We now have a "secret" capability to generate todo lists in markdown. Just add ".md" to a project entry. It will return the project badge entry in markdown format:

We can add links to this, but first we need to see if it's worth using :-). Thoughts?

@SecurityCRob
Copy link

SecurityCRob commented Jan 31, 2024 via email

@david-a-wheeler
Copy link
Collaborator Author

Note: This works in any supported language. E.g., for French instead of English use:

https://www.bestpractices.dev/fr/projects/1.md

@jmertic jmertic mentioned this issue Jan 31, 2024
Closed
@TonyLHansen
Copy link

It looks potentially useful.

@david-a-wheeler
Copy link
Collaborator Author

It looks potentially useful.

Great! That was certainly the goal :-).

Please try it out to confirm or deny the "it's useful" hypothesis. If someone confirms it is useful, we can add a link somewhere so people can find this new capability.

I intentionally generated a todo list for only one level. The todo list is already long for any one level; showing all levels at the same time would be overwhelming I think. The goal is to help people complete the work, not to overwhelm them :-).

@lucasgonze
Copy link

The todo list is already long for any one level; showing all levels at the same time would be overwhelming I think.

I tried out the output in a markdown editor (https://markdown-editor.github.io/) that can show just the rendered version. This was not too much. The code version is super hard to read, though.

I'm not sure it's tenable to show just one level. Fortunately the current output that I'm seeing does have all the levels.

The reason showing all the levels at the same time is overwhelming is that the best practices badge is substantive. There's a lot going on, but it's for good reason. It's just that projects working through it need to be organized and have follow-through.

@TonyLHansen
Copy link

TonyLHansen commented Jan 31, 2024 •
edited

Hmmm, can criteria_level be a list? as in "?criteria_level=1,2,3". That could let you get just the single level, or multiple levels as needed.

@david-a-wheeler
Copy link
Collaborator Author

It could be a list, but that's inconsistent with other things, and a pain to process.

An alternative would be to generate the full sequence if no level given, and only those criteria at a level if the level is specified. If you want more than one, you probably want them all :-).

@TonyLHansen
Copy link

+1

@david-a-wheeler
Copy link
Collaborator Author

The generated markdown seems to work really well at https://markdown-editor.github.io/ so that's encouraging.

@david-a-wheeler
Copy link
Collaborator Author

"No levels means all levels" drafted here:
#2106

@david-a-wheeler
Copy link
Collaborator Author

You can now get todos in markdown.

To generate a markdown for all levels for project 1 in English:

You can request specific levels and/or a different locale:

Checkboxes are filled in for "Met" and "N/A". They are empty for "Unmet" or "?" (Unknown).

What do you think?

@david-a-wheeler
Copy link
Collaborator Author

If this works, we now need to figure out how to let people find this capability. I suggest adding some text somewhere on a badge entry, e.g., when viewing https://www.bestpractices.dev/en/projects/1. Where should that text go? What should it say? What part would be a hyperlink to it? Suggestions welcome.

@david-a-wheeler
Copy link
Collaborator Author

Note: GitHub and GitLab support checkboxes. CommonMark doesn't support checkboxes. However, the only alternative is to use HTML, but many systems won't allow "raw" HTML & that stuff is hard to read. I think anyone who wants to use a checkbox-based todo is going to use a markdown system that supports checkboxes.

@david-a-wheeler
Copy link
Collaborator Author

(Reposting, there was a weird problem)

Pandoc also works well. I think support from GitHub, GitLab, and pandoc is sufficient. Here's the proof. Given file x.md:

- [x] This is <details><summary>[foo]</summary> some details</details>

And running command:

pandoc -f 'gfm+task_lists' -t html x.md

It produces:

<ul class="task-list">
<li><label><input type="checkbox" checked="" />This is
<details><summary>[foo]</summary> some details</details></label></li>
</ul>

I suggest noting the pandoc command in some "details" for the link to the markdown generated file.

@lucasgonze
Copy link

I think support from GitHub, GitLab, and pandoc is sufficient.

I agree. We're pushing the limits and it's reasonable to say that some things are not possible.

@lucasgonze
Copy link

lucasgonze commented Feb 2, 2024 •
edited

we now need to figure out how to let people find this capability.

Research

Is there already a way to find the JSON and (I think) XML export formats? I don't think so, but if there is then we should add one more format.

Glyphicons has these relevant icons:
Cloud download: image
Save / Save As image

This application has a multistep flow for exporting data that uses a modal dialog with a format chooser. It is great from a usability POV but too complicated as far as implementation:
https://www.frontitude.com/guides/export-project-content-as-json

Experiments

Experiment 1: on the panel title

image

That textual approach doesn't work at all. Possibly a Markdown icon that looks like a button could work.

Experiment 2: text in the footer

Add this:

<em class="glyphicon glyphicon-save"></em> Export data as <a href="">Markdown</a>, <a href="" class="glyphicon glyphicon-save">JSON</a>, <a href="">XML</a><br><br>

Just above:

This data is available under the Creative Commons Attribution version 3.0 or later license (CC-BY-3.0+).

Screenshot:
image

@david-a-wheeler
Copy link
Collaborator Author

Text at bottom makes sense. I'd want to be able to generate Markdown for two cases, "current level" and "all levels".

@lucasgonze
Copy link

Text at bottom makes sense. I'd want to be able to generate Markdown for two cases, "current level" and "all levels".

Mockup of current level:
image

Code:
image

This code displays an icon but is not itself an anchor or clickable target.

Note that the title attribute is good for accessibility and also creates a tooltip to explain the feature:
image

@david-a-wheeler david-a-wheeler mentioned this issue Feb 6, 2024
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@lucasgonze @david-a-wheeler @TonyLHansen @SecurityCRob