Edit documentation in TW and use Github API to create PRs directly?

[saqimtiaz]

I have thrown up the code here: GitHub - saqimtiaz/tw5-docs-pr-maker: Create Docs PRs from TiddlyWiki

And set up a demo that is regenerated every 5 minutes with the latest tw-com content:
https://saqimtiaz.github.io/tw5-docs-pr-maker/

[Mark_S]

@saqimtiaz

I think the primary obstacle is going to be when someone submits a PR and gets asked to correct something minor before it can be merged.

If it’s truly minor they can fix it from GH. If it’s not truly minor, they can submit a new PR and cancel the old one.

@saqimtiaz

The main concern I had was users forgetting brackets around tiddler titles with spaces and thus creating broken PRs. I have introduced some wikitext handling to prevent this.

Dragging and dropping titles automatically inserts the brackets.

My assumption is that anyone submitting documentation knows TiddlyWiki really well – they know about TW titles. They know about saving. They just don’t know or want to know about the arcane, arbitrary, byzantine world of GitHub.

@saqimtiaz

What would be helpful here both for this work and for updating docs via node.js is a $:/config/FileSystemPaths tiddler for the tw-com edition.

I think most users are smart enough to put new tiddlers into directories that match similar existing tiddlers. I can’t imagine that there’s any FSP setting that can substitute for human pattern matching. We could list out the existing directories and have the user choose from one of them.

@saqimtiaz

Right. I think the real issue is figuring out the user story. Is this installed on TiddlyWiki.com?

That would be ideal. But it obviously depends on if Jeremy approves.

Otherwise, if there was a way for a mirror site that is identical to TiddlyWiki .com except that it has your documentation tiddlers, that would be great since it would allow people to make changes from anywhere even without access to a hard drive.

Or, people could just dnd your files into their own copy of TW, save, and reload.

@saqimtiaz

What if the user is working on larger changes and wants to save changes during their work (download saver?).

I think we have different starting places in mind for the user. Any user submitting documentation is likely pretty well versed in the TiddlyWiki world. They know about saving. They know about the emergency saver. Or we can remind them of it if it’s a concern. They can save their work and come back if they need to submit a 2nd PR. Or they can wait for the original PR to get merged, and then work on that.

Because of the one-shot PR mechanism, the ideal use would be for someone who is making a set of changes in one session. And then come back after the changes have been merged if further enhancements are required. Someone who is doing an entire rewrite of the TW core documentation should probably put on their GH hat and do it from a local repository.

I just realized another issue. Does the current code handle tiddler renaming and/or deletion?

Thanks!

[pmario]

@saqimtiaz

And set up a demo that is regenerated every 5 minutes with the latest tw-com content:

hmm. I think 5 minutes is a bit overkill for a prove of concept.

[saqimtiaz]

It makes no difference, GH Action cron jobs run according to availability so it averages out to a few times per hour at most.

[saqimtiaz]

@Mark_S

I think most users are smart enough to put new tiddlers into directories that match similar existing tiddlers. I can’t imagine that there’s any FSP setting that can substitute for human pattern matching. We could list out the existing directories and have the user choose from one of them.

FileSystemPaths was created for exactly this and the fact that they aren’t configured for tw-com is a constant pain point on node.js as well. Most documentation tiddlers follows very obvious patterns for which directories they go in to.

That said, if someone wants to explore a UI for specifying directories that would be welcome.

@Mark_S

Otherwise, if there was a way for a mirror site that is identical to TiddlyWiki .com except that it has your documentation tiddlers, that would be great since it would allow people to make changes from anywhere even without access to a hard drive.

That is what the demo currently does, though ideally we would have the main TW repository trigger an update of the mirror (via a Github Action) every time there are new changes to the tw-com branch, rather than have it on a timer.

@Mark_S

I just realized another issue. Does the current code handle tiddler renaming and/or deletion?

To TiddlyWiki, renaming a tiddler is deleting the tiddler and creating one with a new name. The plugin we are using handles deleting files but we would need to add an affordance for that in the UI, or have a way to track and remember renames and pass that to the code making the PR.

[Mark_S]

@saqimtiaz

$:/config/FileSystemPaths tiddler for the tw-com edition.

If you had this, how would you use it? And the meta question, why is it not already populated?

My question in the other thread about performance actually relates to this. I was analyzing the official paths. There are 1383 unique tiddlers, and 65 unique paths.
There’s no guarantee, of course, that those tiddlers can all be sorted into the paths by particular rules. It would take awhile to analyze them, and it may be that some existing tiddlers would either need to be moved (physical location), tagged, or be renamed to fit the pattern. So a substantial sub-project. Is it really worth pursuing that approach?

[saqimtiaz]

@Mark_S

If you had this, how would you use it? And the meta question, why is it not already populated?

If the file system paths filters were defined, they could be used to generate file paths for every new tiddler. We already do this in the core for node.js and it is relatively straightforward.

As for why it isn’t populated I can only speculate the facility was introduced after the edition was already established and no one has done the leg work.

@Mark_S

It would take awhile to analyze them, and it may be that some existing tiddlers would either need to be moved (physical location), tagged, or be renamed to fit the pattern. So a substantial sub-project. Is it really worth pursuing that approach?

It is a constant pain point when writing documentation for new features in the core, so I do feel it is worth doing. It need not be a part of this work however.

If someone wants to take on creating an intuitive UI affordance for users to be able to specify the path for a new tiddler I am very much open to that. The UI should be all wikitext work and if that is in place I can try to find time to wire that up to the JavaScript.

My only concern is that the user experience should be as intuitive as possible to allow less experienced users to be able to make smaller documentation contributions and corrections as well if they wish to do so.

[Mark_S]

I may be working towards something like

[pmario]

@saqimtiaz

My only concern is that the user experience should be as intuitive as possible to allow less experienced users to be able to make smaller documentation contributions and corrections as well if they wish to do so.

That’s why I would like a “tags” approach. So if newbie users tag a new tiddler it will be automatically sorted into the right path.

If there is no tag, they land in “tiddlers” … and we will need to tag them later … or they stay there

[pmario]

I also think it would be an advantage, if someone would the TW TOC. There are a lot of tiddlers that are shown in several places. From my point of view that’s a real pain point, even for experienced users.

At TW-com I use search only. The TOC is completely useless for me. … It would be useful if it would “auto-expand” and show open and viewed tiddlers … BUT that’s a completely different topic.

[jeremyruston]

@pmario

I also think it would be an advantage, if someone would the TW TOC. There are a lot of tiddlers that are shown in several places. From my point of view that’s a real pain point, even for experienced users.

Just to say that that is intentional, and is intended to help with the cases that topics belong under multiple headings. For me, that ability is a great advantage of TWs TOC compared to a regular outline or directory structure.

[Mark_S]

Well, talk about winning the battle but losing the war. I’ve got the interface done (donish, there’s always more ) but I’m getting this message when creating the PR:

There was an error in creating the PR. HttpError: tree.path contains a malformed path component

I’m wondering it something in the PR kit doesn’t like new tiddlers with a specified path? The only thing my code does is update OriginalTiddlerPaths . So when the tiddler gets pushed, and the API finds it doesn’t have a match (tree.path ?) … it complains? Maybe?

Here’s the two tiddlers I’ve worked with –

2021-10-27-Push_PR.json (4.0 KB)

[saqimtiaz]

@Mark_S I think there is an issue with the originalTiddlerPaths in the wiki I set up to be auto built with fresh content from tw-com. As an artifact of the build script those paths are not correct and may be causing the issues you are experiencing.

I have a particularly busy day today so wont get to look at this before tomorrow at the earliest. In the meantime, you might be able to test your code with the original demo which does not have the same problem: Create Docs PR from TW

I pushed a very quick fix that I think should resolve the problem. Let me know if it persists and I will try to take a look tomorrow.

Note that the originalTiddlerPaths no longer reference the node_modules folder (they never should have, that was introduced by the auto build process) so you may need to tweak your macros accordingly.

[Mark_S]

For anyone who wants to try it so far, drag and drop the following into Saq’s demo page.

Hmm. If this is acceptable, I guess some additional info should be added to notes.

2021-10-28A-Push_PR.json (4.2 KB)

[pmario]

Something strange is going on.

• I did define a path and clicked the + button.
• But now the UI is gone.
• I don’t know what I selected
• I can’t change it …

Since I don’t know which path I did select I basically have to start from scratch

As a user I’d expect:

• It shouldn’t be needed to click the + button to confirm a path for a new tiddler
  • Selecting a path from the dropdown imo is enough confirmation
  • Selecting a path from the dropdown doesn’t activate the “Make PR” button
• Once I’m done with all paths, I would expect a button eg: “Confirm Settings”
  • near the “Make PR” button.
• The path settings should be visible and changeable at all times
  • even if the “Make PR” button is active already it should be possible to change paths
  • If a path is changed
    • “Make PR” is disabled and
    • the “Confirm Settings” will be needed again
• Clicking the “Confirm Setting” button should activate the “Make PR” button

Just some thoughts.

[Mark_S]

@pmario

Something strange is going on.

• I did define a path and clicked the + button.
• But now the UI is gone.
• I don’t know what I selected
• I can’t change it …

Clicking the button was a commitment to the path. Presumably people will make a conscious choice. But I see your point.

The final “choice” could be moved to the end, next to the PR button.

But the reason you have to make a choice at some point is because it’s using the original paths to determine which items do not have an assigned path. Once you add the selected path (either by individual button or a final choice button), your tiddler becomes just like any other tiddler and so disappears from the listing. The PR button needs to know that OriginalFilePaths is OK before processing, so that’s why there needs to be a “commitment” at some point.

I suppose the “Confirm” button could turn into a “Reset” button, so you could undo your OFP changes, make new selections, etc. Since the selections are maintained in temporary tiddlers, your last path settings should still be there.

Maybe wait and see if there are any other opinions about interface, before spending more hours working on it.

[saqimtiaz]

Hi @Mark_S, found the opportunity to take a quick look. Thank you for working on this.

I think this is a good start. Some quick thoughts on potential UI improvements:

• It would be good to fix the relative column sizes (this is in the ugly table I implemented, not your additions) so they don’t change as one enters data. That can be jarring and potentially confusing.
• Maybe only show the table row with “Specify file paths” when there is a title that is new is entered into the textarea?
• I like that you can specify different paths for different tiddlers.
• Perhaps we get rid of the confirmation for the paths button, enable the “Make a PR” button as long as a path has been selected for all new tiddlers, and update OriginalPaths when the “Make a PR” button is clicked? This would also allow users to see what path they have selected in the select dropdowns and change it if necessary.
• This is superseded by the above suggestion: It might be nice to have a “show paths” option to show paths for the titles that will be in the PR, in case one wants to double check what was entered before submitting.

[Mark_S]

@saqimtiaz

• It would be good to fix the relative column sizes (this is in the ugly table I implemented, not your additions) so they don’t change as one enters data. That can be jarring and potentially confusing.
• Maybe only show the table row with “Specify file paths” when there is a title that is new is entered into the textarea?

Am I correct in thinking that these will require us to jettison the current pipe-based table in favor of an HTML table? Like I don’t think we can provide sizes with the pipe table and think that it’s not possible to wrap a piped row with list/reveal?

Thanks!

[saqimtiaz]

@Mark_S I think you’re right, an HTML table would be the way to go about it.

A wikitext table could work for the column widths using a CSS selector like td:first-child but the conditional display for the bottom row would still necessitate HTML.