Demo: updating docs and creating a PR from within TiddlyWiki

Community Projects Documentation
#41

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:

drawing

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.

#42

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.

#43

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.

1 Like
#44

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
#45

@saqimtiaz Here’s a preview of the ready favicon (png):

prmaker-128

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
#46

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
#47

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
#48

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
#49

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?

#50

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.

#51

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
#52

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.

#53

Have just followed the steps and linked up. Good starting wizard. Now I just need something to say!

#54

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 jsonstringify and stringify operators 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.

#55

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.

#56

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?

#57

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.

#58

@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.

#59

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
#60

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?