That’s right. The user has to be online, if they want to create a PR. So a CDN should be fine.
I think, this would be a 3 minute video, to show how it will be used. … As a side effect it will also help users to use the GitHub saver.
Here is what the really ugly prototype looks like:
As an aside, it would be nice to have a wikitext affordance to check if a password has been set in local storage. Only to verify if it exists, not to retrieve it.
@saqimtiaz this is a very good idea. I am sure we can get a sufficient number of developers and enthusiasts to utilise this method. This will itself help build the documentation.
However I am not sure a novice or even regular users/designers will adopt this. For this reason I think a/the discourse Documentation category could be a place for contributors to post updated tiddlers that those with this ability may load into their Git activated wiki and submit on behalf of the contributor.
- Thus Being able to annotate such PR’s with the contributor or even a talk.tiddlywiki.org link makes sense.
- To make it easy share instructions how to export a modified tiddler or tiddlers for application to the documentation.
- Consider the possibility of being able to submit changes to other wiki repositories/trees.
** Eg a links repository, extended documentation or references, self submitted references etc…
Perhaps in the future a publicly accessible GuitHub could allow “anon” contributions into a repository from a website. Still demanding a review before actioned.
Good work @saqimtiaz, looking out for community needs.
@pmario @jeremyruston @boris and @everyone
This is what a PR generated via TiddlyWiki looks like:
(edit: replaced with a better example)
What I did:
- Edited the tiddler “enlist-input Operator” in TiddlyWiki
- In the interface shown below:
- Added a PR title and PR message
- Added the tiddler title
- clicked on “Make a PR”
- smiled like crazy and realized I am up way too late.
I think even I would find this an easier way to make docs PRs than my current node.js workflow.
Good night!
Edit: if the user does not already have a fork of the TiddlyWiki repo it is automatically created.
4 Likes
@pmario asks on Github:
Is it possible to add changes (new commits) to those tiddlers later on, or is that a new PR?
With the current code it would be a new PR. However, it is possible to implement the ability to add new commits to the same PR as well.
We are using 2 dependencies, a low level library (octokit) that covers the entire Github API and a plugin for it that makes it very easy to create PRs. So either we use the low level library to update the PR or we find a plugin for it.
The real catch is going to be the user side of things and the copy of tw.com that they use.
- we need to make sure they always start with a fresh copy of the site
- if we want to allow updating a PR, then they would need to have saved their changes in TW somewhere
- unless we use Github actions to generate a TW file for every PR, and then that file can be used to further update the same PR as long as it hasn’t fallen far behind the
tw.combranch in terms of changes.
- unless we use Github actions to generate a TW file for every PR, and then that file can be used to further update the same PR as long as it hasn’t fallen far behind the
- Or we have a one click option to clone
tw.comto say TiddlyHost (with their permission and consideration of cost) as starting point for each PR. The wiki persists at TH while the PR is open.
OK. I haven’t had a look at the dependences yet. …
For the start I would say “keep it simple” and iterate often. So we can deal with several commits to the same PR later.
@pmario I’ll post a demo soon that everyone can play with. It will create PRs but it will target my fork so as to not spam the main repo while testing
1 Like
I have posted a demo:
I don’t want to spam your account either. … What do you think, should we create a “throw away” organisation, that we can “spam” with test PRs without collecting too much garbage in our own repos?
I did have a closer look at octokit.js … It seems once a PR is created, it will automatically pick up new commits to files in the same “feature branch”. …
So instead of creating a new PR we just need to update the file. … The only thing which seems to be important is the “SHA of the parent commit” … So it may be important what the “create PR workflow” returns. … So a bit more testing is needed.
We can, though it really isn’t a problem to spam my fork. I can simply delete my fork and recreate it to get rid of the noise. When I don’t have open PRs I consider forks of public repos to be disposable.
I do have a throwaway account I created for testing CI for twlinks, I can look up the details for that later if need be.
Yep if we use the low level octokit it is all doable. The create PR plugin makes creating a PR easier but only returns the PR number. So either we need to use that and the branch name to fetch the SHA for the parent so we can update the same branch, or just handle PR creation ourselves with octokit and not use the plugin. Both would work.
Anyway, I do think we shouldn’t get too caught up on that at the moment and consider that as Step 2, with Step 1 being getting a decent workflow in place for creating a PR in one go (without facilities for updates).
(An important bit with being able to update a PR is that you will need to have the TiddlyWiki you previously used to create it.)
Leaving this as a note to myself (easy fix): files created for new files don’t currently get a .tid extension.
That’s right. I think the PR-plugin abstracts a lot of “octokit.core” complexity away and is a very good start. …
As a user of our PR workflow I would like to have a bit more feedback. The “button that links to the PR” at the end isn’t enough for me.
Some messages like like:
- Creating a pull-request
- Work in progress … (may be animated dots)
- Success - Link to PR
would already work for the beginning. … Just some thoughts.
@pmario agreed, as I mentioned both the user workflow and the UI need work. Definitely needs more error handling too.
What is there now is what I considered the absolute minimum for a demo.
Do feel free to tweak and modify if you feel inspired.
Various thoughts
I feel like this is usable as is, solving the problem of multiple tiddlers, viewing the tiddler as edited, and eliminating the need for a local repository. For experienced users like Pmario it may be limiting, but for everyone else it’s a door-opener. Among other things, it means you can be at any computer, maybe even a tablet or phone, when you submit changes.
I’m not sure what interface improvements would make it qualitatively better. Dragging and dropping your tiddlers from the “Recent Tiddlers” tab is pretty easy for anyone who’s at the level of someone who is interested in doing this.
The main thing missing from the UI might be a way to add paths for new tiddlers. I’m thinking they could be inserted into “$:/config/OriginalTiddlerPaths” ?
Maybe also instructions to the user to refresh their fork if it’s been awhile since submitting updates. Though I’m not sure if that’s even necessary if the source tiddlers are coming from tiddlywiki. com.
Apparently every PR has to be submitted on a unique branch, which is unfortunate. But the form could allow you to submit a branch name, or branch prefix, for every PR. Which would make it easier for someone who wants to do final touch-ups by hand at GH.
The plugin only allows the creation of PR’s. One way around this limitation would be to have a convention where fix-it PR’s could be submitted with prefix “Supercedes PR#xxxx” . Then whoever is doing the pull could know to skip the prior PR request. This is operating on the theory that most of the time the first PR is good enough.
If the request form and code were included in TiddlyWiki .com , then just by refreshing the page a user would have the latest set of tiddlers. (minus any that haven’t been merged yet).
Hi @Mark_S thank you for the considered thoughts, very helpful.
Note that I have updated the demo this morning with a few changes:
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. Without delving into the Github UI there will be no way to easily update the PR that they have created. But otherwise I agree, this should already be a step forwards.
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.
@pmario and I discussed this in either this thread or the one with the demo. Even on node.js there is nothing to guide where new tiddlers go in the directory structure. 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.
Adding new tiddler paths to “$:/config/OriginalTiddlerPaths” doesn’t help much if all new tiddlers are just being added to the root of the tiddlers directory. I would rather users don’t have to decide where the tiddlers go and it can be calculated from the $:/config/FileSystemPaths tiddler.
Right. I think the real issue is figuring out the user story. Is this installed on TiddlyWiki.com? or at a different URL that we link to from tw-com and which mirrors it but also adds the plugin? What if the user is working on larger changes and wants to save changes during their work (download saver?). Figuring out a recommended process and documenting would probably help those less familiar with working with TiddlyWiki.
Yes that kind of thing can work. What would be needed is a way for them to continue where they left off with their changes. Do we assume that the user has saved the file in which they made changes? If we had the ability to generate TiddlyWiki files from PRs that could help (and is possible via Github Actions). They could take the file from their previous PR and use that as a starting point for revising.
I don’t expect to have the opportunity to devote much if any time to this in the near future. So I am hoping the community can brainstorm around this and figure out next steps towards getting this usable by those less TW or tech savvy, and then I can chip where really needed when I have the chance.
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/
1 Like
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.
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.
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.
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.
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!