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.
1 Like
@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.
2 Likes
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.
1 Like
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.
1 Like
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.
1 Like
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:
- the facility to load an existing PR by URL to make further changes to it, this should eliminate the need to backup your submitted changes
- saving a PR as a draft for work in progress
- updating already submitted PRs
- deleting tiddlers
Improvements still pending include:
- a lot of testing
- excluding tiddlers with no changes from the PR. This can currently cause errors.
- updating the button labels, for example Submit should become Update when an existing request has been loaded.
- adding steps to the intro tour to explain loading a submission and making further changes to it, how and when to create drafts.
- adding a comment to each PR that provides a link that opens said PR in the edition for contributing docs, to make it easy to respond to requests for further changes
- skipping prompting the user for their GitHub username and instead retrieving it using the auth token.
- a review of the UX with an eye towards removing clutter or distractions from the added features that might confuse new users
2 Likes
I did just run a test with 9 different commits.
They different steps are documented in the OP
The whole system seems to be very robust. I did not get any error messages from the API.
The only problem that came up was a server side commit 7 which was overwritten by commit 8 from the client. The client was not refreshed.
I think that’s what you meant with: “Improvements still pending”
- excluding tiddlers with no changes from the PR. This can currently cause errors.
I highly appreciate the work you do, to make the documentation workflow easier.
Have just followed the steps and linked up. Good starting wizard. Now I just need something to say!
I have attempted to load a PR from official repo, modify, and submit it to test repo.
- Loading PR from link worked only after changing setting to official repo.
- The changes from the existing PR have been loaded correctly.
- Changing setting back to test repo and submitting (whether as draft or active PR) showed the message “There was an error in submitting the update. HttpError: Not Found”, but the changes appear to have been submitted to the official repo: Improve
jsonstringifyandstringifyoperators docs by mateuszwilczek · Pull Request #7650 · Jermolene/TiddlyWiki5 (github.com) (three times, because I tried to submit it as draft or active a couple times). The changes to PR description are not visible on GitHub.
This docs PR was small and still a draft, so no damage has been done. I guess I shouldn’t have tried to take PR from one repo and push to the other one. I will continue testing using only the test repo now.
The ability to switch target repos is only there to allow me to test without spamming the TiddlyWiki repo, and will eventually be removed or hidden. Loading a PR from one and submitting to another is not intended to be supported.
The “Not Found” error you got was because a PR with the given number did not exist for the selected target repo, however your branch was still updated so any pre-existing PR that uses that branch gets updated.
Thanks for clarifying!
Anyway, doing everything in test repo, creating a draft, then loading it, editing further including editing PR description, and submitting as active PR has worked correctly.
Out of curiosity, what are the <small> tags around "Submitted using https://saqimtiaz.github.io/tw5-docs-pr-maker/dev/dev.html." for? They are not rendered in GitHub web (the text is not smaller), only when editing the description, and when loading to PR Maker, they are shown in plain text in the description editor. Is there any place where their effect is visible? Or is it for testing only?
I think it would be good to somehow differentiate the PR Maker’s tiddlers (Submit documentation updates, Contribute Settings, Contribute Help), so that it’s immediately clear they belong to PRM and are not a part of the original site.
This should be done carefully, as not to overwhelm and distract too much.
The possible solutions that come to mind are (not all at once of course):
- Common tiddler icon, maybe the one used in favicon, I could modify the SVG to be usable in TW.
- Namespacing, e.g. PRM/, PR-Maker/, DocsEditor/.
- Common styling, e.g. border like in this example TiddlyWiki — a non-linear personal web notebook, my least favorite solution as it adds clutter.
Other UI elements like walkthrough, yellow tour popup, sidebar buttons, could also be more consistent with each other’s style, but I don’t have any constructive ideas about how to do it, I will try to come up with something.
@saqimtiaz the dev version under https://saqimtiaz.github.io/tw5-docs-pr-maker/dev/dev.html seems to be stuck on v5.3.0 and does not reflect some recent documentation updates. Is this to be expected, because it is still in development?
Edit: it is still useful, due to its ability to load existing PR and push to it. But because it doesn’t show up-to-date docs, it is not reliable on its own, without the “stable” version.
The dev version was uploaded manually as a one off for testing. I’ll try to find time this weekend to merge those changes into the main index.html that is automatically refreshed with the latest changes.
2 Likes
Thanks, that would be great!
When you’re at it, it would be good to change the favicon I provided from the ICO format to PNG. I have also left a note in the issue ( [Enhancement] Custom favicon different from tiddlywiki.com · Issue #5 · saqimtiaz/tw5-docs-pr-maker (github.com) and linked to the explanation there.
Have you considered also changing the site title of the PR Maker, to make it clearly stand out from tw com?
I have just pushed a small change to the documentation submission edition which removes the need for loading external libraries from a CDN by packaging them into the plugin itself. Hopefully this will help those users who have run into problems with access to the CDN.
1 Like
Now that this has been in use for some time, hopefully without bigger issues, I was thinking maybe we should:
- mention it in the Improving TiddlyWiki Documentation tiddler.
- add a link to this edition in the pink ribbon on tw-com. Currently it looks like this:
The external link leads directly to editing of the .tid file of that tiddler in GitHub repo.
It would be trivial to add another link that leads to the given tiddler in the docs submission edition.
3 Likes
Thank you @vilc, those are great suggestions.
A PR from @pmario that updates the “sources” panel to point to the PR maker was just merged. It would be good to add a tiddler specifically about the PR Maker, and link to it from both places. We should also link to it from the “Improving TiddlyWiki Documentation” tiddler.
3 Likes