The “x” at the bottom of the intro lets you exit the tour at any time. Having a more explicit exit button on the first step might be helpful though. I’ll give it a go next time I work on this.
Also, contributions are very welcome: GitHub - saqimtiaz/tw5-docs-pr-maker: Create Docs PRs from TiddlyWiki
@jeremyruston would it be acceptable for a documentation PR from a new contributor to include the CLA signing in the same PR?
I am considering building in a step in the tour for the PR maker, which checks whether the user’s username is already in the CLA and if not, prompts to read the CLA and confirm that they want to sign it. The modification to the CLA would then be part of the same PR.
I’ll have a look. — There is a second issue with the “submission” form. It says “Provide a GitHub auth token”. IMO there should be a button as in the tutorial that directly jumps to the tocken page.
Just a convenience improvement.
I did just create a PR and I love the confetti, but they only cover a very small portion of the screen. I’d like to have it all over the screen and may be more.
Love it! 
IMO that would be more like it.
<$button>
<$action-sendmessage $message="tm-confetti-launch"/>
<$action-sendmessage $message="tm-confetti-launch" originY=0.6 spread=100 delay=300/>
<$action-sendmessage $message="tm-confetti-launch" originY=0.55 shapes=circle spread=130 delay=400/>
<$action-sendmessage $message="tm-confetti-launch" originY=0.55 shapes=star spread=180 delay=500/>
Launch three staggered rounds of confetti
</$button>
Yes we do accept PRs like that. I have a slight preference for the signature being a separate PR so that it can be merged swiftly even if the other parts of the PR need further discussion, but I don’t think that that matters in this situation.
I have pushed an update that prompts the user for their Github username, checks if they have previously signed the CLA and if not, prompts the user to sign it. The CLA is signed in a separate PR.
https://saqimtiaz.github.io/tw5-docs-pr-maker/
This step as well as the one for the authentication token are skipped if the relevant conditions are met (CLA already signed and authentication token already provided respectively).
There probably needs to be handling for expired tokens that need to be replaced. I may opt for a control panel tab that shows all relevant settings.
Hmm realising also that the CLA step needs to come after the Auth token step.
It has been pleasing to see two different users make documentation contributions using the PR maker recently, thank you.
If you ran into any problems or issues, please do let us know.
I intend to add a step that prompts the user as to whether to save a backup of the changes they are submitting. This is useful if further changes are requested to the change that has been submitted.
@saqimtiaz I made two PRs since yesterday using the PR Maker. I didn’t have any problems. It is an enormous improvement to the workflow of documenting, thank you!
I have some ideas for small improvements.
Backup
Do you intend the backup prompt to export a json with the modified/submitted tiddlers? I think it is a great idea. Right now I downloaded the whole wiki as a backup, but it is obviously a lot of overhead. Maybe the backup should be also available separately (a second floating button?), so that the user can backup the changes during work, before they are ready for submission.
Skip button for the introduction
I agree with @pmario, I would like there to be a simple way to immediately enter the username/token and skip the introduction. The X button closes the intro, but leaves no easy way to enter username/token (or have I missed it?). Btw the intro itself is great for new users, simple and straightforward!
Custom favicon and site title
I think a favicon and site title differing from the tiddlywiki.com would help the PR Maker stand out in case one has both sites opened. I find it useful to have tiddlywiki.com opened aside as a quick reference of how the docs looked before my changes, or to quickly test something without messing with the actual contribution.
Yes that is the intention, along with the PR title and description. There is a button currently in the submission form that lets you download the modified tiddlers via Advanced Search, but it can be made more convenient.
If you don’t have the auth token filled in, the submission form displays a field asking for it. The username is only needed to check if the CLA has been signed. See the screenshot at the end of this post.
That makes sense, thank you. I would welcome contributions for an appropriate favicon. We just have to be careful because every tiddler we customize, can no longer be a part of a submission but the site title and favicon make sense.
I am considering either a settings button that opens a settings panel that lets users easily change auth token, username etc; or a button to switch to an advanced more that displays more settings.
Ok, in this case the current functionality is sufficient. I think this information should be more apparent, without it I felt kind of lost after skipping intro, not knowing that username is not necessary and the token will be asked for when needed. I don’t have an idea where to put it though, so that it’s easily accessible for “recurrent users” that may want to skip the intro, but not overwhelm new users that go through it.
The first simplest idea I had was the original round favicon, but with a different color, e.g. green (as in active PR) or grey (as in draft PR). Different color versions of this favicon are already in use by various TW sites, e.g. prerelease (black), dev (orange), community (turquoise), I don’t know if using one with another color for PR would make things clearer or more confusing.
Here is a quick draft of my second idea:
This would have some design similarity to the TW favicon (round background, white symbol in the lower portion, clipped by the lower margin). Some minor adjustments would be due of course, e.g. thicker lines for better readability at small sizes.
It seems like there is a bug with the CLA signing where for some users, their name is being added twice. I will investigate as soon as the opportunity presents itself.
I quite like this, thank you. If you or anyone else has the skill and time to get this into usable shape, it would be much appreciated.
I’ll work on it when I find some time, maybe this weekend. Making it as a simple svg or png is straightforward, but i think it will be best in ico format, like the original. It allows for exact pixel tweaking for small sizes (as in browser tabs) so it’s more manual work, but looks much crispier.
@saqimtiaz Here’s a preview of the ready favicon (png):
Here’s the updated $:/favicon.ico tiddler, containing the favicon in ico format (sharing ico files is not supported on this forum):
$ _favicon.ico.json (12.8 KB)
If anyone would like to improve or change it, I can provide the source files.
Edit: updated the json file to include a slightly improved version of the icon, the same as in the package posted on github, see below.
Another great design, thank you @vilc. I think it would be helpful to have both an SVG representation and the original file in the repo as well as the bitmap version.
I have dropped an archive with all versions of the file, including the source svg, in this issue: [Enhancement] Custom favicon different from tiddlywiki.com · Issue #5 · saqimtiaz/tw5-docs-pr-maker · GitHub, I think it will be easier to discuss eventual further details there.
Many thanks @vilc, much appreciated. I am working on a substantial update to the documentation contribution mechanism and will add the icon at the same time.
I’m writing here, because it’s related to documentation and GitHub, but this could be implemented in tiddlywiki.com as well, not necessarily in PR Maker.
This conversation, starting from the linked post:
gives me an idea. It’s not trivial to know, that there are pending docs changes on a given tiddler. I know nothing about GitHub API or HTTP requests, so I don’t know how much sense it makes to implement.
The idea: upon editing a tiddler, a check would run to see if any PRs are touching this particular docs tiddler, and display an alert with links to to those PRs. Or, if that is not possible/ not worth the effort, a simpler solution could be a link to PR search for changes to that file. Before starting to edit the docs, one could easily check if there are no pending changes to the tiddler.
Does this make sense? Or is this situation (two users independently working on the same docs) so rare, that it’s not worth the effort?
Hi @vilc. That is an interesting idea. One of the challenges I am facing at the moment as I add more features to the PR creation mechanism is that it adds more clutter and potential confusion for non-technical users. If you also take into account the time and effort it would take to implement each feature, and that contributions to the documentation are sadly quite scarce, it seems like something that would be useful very rarely.
However, should the volume of documentation contributions pick up in the future, it would be worth revisiting the idea. Especially since some of the new features I am working on would allow a user to make further changes to an existing PR and submit it again.
I have been working on a complete rewrite of the mechanism for contributing docs via PRs. It needs more testing and some polish but I have uploaded it for feedback separately since it will be a few weeks before I am able to work on it further: TiddlyWiki — a non-linear personal web notebook
By default this will create PRs against a test repository, though you can switch to the TiddlyWiki5 repository from the settings tiddler.
Improvements include:
Improvements still pending include:
