Contribute Documentation with edit.tiddlywiki.com

#1

Contribute with edit.tiddlywiki.com

The former PR-creator wiki has been refactored, to allow to create documentation pull requests using a simpler mechanism.

You only need to be signed in to your GitHub account to be able to contribute to the TW documentation using TiddlyWiki UI to edit and create new content.

Important

We do have documentation style guides, which you should try to use, to make contributions easy to handle.

If you open edit.tiddlywiki.com you will be greeted with a step by step introduction tour.

image
image2399Ă—1201 132 KB

  • If you reach the sign in page the first time and click “Sign in with GitHub” (1) button a popup window will be opened
  • This dialogue will allow you to select the existing user (2) or
  • It will allow you to create a new user
  • If you do not have a GitHub account yet, you can create one using
    • Your Google authentication manager or
    • Your Apple account
    • Create a New GH account with e-mail and PW (3)

image
image2120Ă—1292 267 KB

  • Once you are signed in
  • The first time – You will need to authorize the TiddlyWiki Documentation Assistant to push PRs on your behalf
  • For this TODO I did create a new wiki-tutor account that I used to sign in as seen in the last screenshot
  • The assistant was created by @saqimtiaz and is linked to the edit.tiddlywiki.com wiki, which is an official part of the TiddlyWiki project

image
image2120Ă—1292 290 KB

  • The “Sign in” button now changes to “Sign out @wiki-totor” as seen in the next screenshot
  • The sign-in automatically expires after about two hours, and you can sign out at any time manually (which not only logs you out but also invalidates the token used to sign you in)
  • Your sign-in credentials are stored in session storage and are cleared when the browser tab is closed.
  • No credentials are stored in any other form of browser storage or in the wiki.

image
image2120Ă—1292 165 KB

image
image2131Ă—1383 187 KB

  • Once the CLA is signed and a PR is pushed to the repo, the page looks like this
  • You can see the PR if you click the link “Request to sign the CLA created”

image
image2126Ă—1406 198 KB

  • You can continue, clicking the “Next” button, till you each the “finished” state
  • The “last” dialogue can be closed with the top left X-button

image
image1920Ă—1270 209 KB

  • Submit Updates (1) button opens the “Submit documentation update” summary tiddler
  • Button (2) "Sign out … " will be active for x minutes. If you take a long time, you will have to sign in again.
  • (3) Tiddler list of changed content tiddlers
  • (4) PR Head line - Should be a short description of the PR
  • (5) PR Description - Detailed info what has been changed
  • (6) Submits the PR
  • (7) Submits the PR as draft. This means, that the PR is not finished yet and it will be updated later

image
image2534Ă—1389 395 KB

  • If you successfully submitted the PR with (6) or (7) the info looks as follows:
  • For this screenshot I did save as a draft.

image
image2534Ă—759 122 KB

  • The link will open the PR draft at GitHub
  • As you can see (4) and (5) form the tiddler is part of the PR now
  • You can add additional info directly to the PR at GitHub
  • Eg: Additional screenshots if needed
  • Additional comments … and so on

image
image2492Ă—1321 377 KB

Have fun!
Mario

8 Likes
#2

is there a way to submit suggested changes to the core available?, perhaps this could be documented somewhere even just a general overview?

#3

What do you mean by “suggested changes to the core”?

#4

You can create a bug report, feature request, or more general discussion on the new issue page at GitHub. You will need to have a GitHub account, but that should be easy to set up. Of course it’s fine to hold a discussion about it here, and only make a feature request when a consensus arises. But the core team may only check the GitHub issues and not these discussions, so it should make its way there eventually.

#5

Thank you for the write up @pmario.

I wanted to further clarify a few details:

  • The TiddlyWiki Documentation Assistant Github app that is used for authorization is an official part of the TiddlyWiki project (as seen in the screenshot)
  • The sign-in automatically expires after about two hours, and you can sign out at any time manually (which not only logs you out but also invalidates the token used to sign you in)
  • Your sign-in credentials are stored in session storage and are cleared when the browser tab is closed.
  • No credentials are stored in any other form of browser storage or in the wiki.
#6

Thank you for this improvement.

I have no problem creating PRs in my day job, and in other FOSS projects, but I struggle here to do them correctly. So I would love to use a PR-maker. But I also didn’t like the previous design that stored my tokens in local storage. This seems better, and also allows you to revoke tokens if there seems to be an issue.

Unfortunately, I cannot test this at work, since GigantiCorp has blocked access to https://sq-github-auth.saq-imtiaz.workers.dev/auth. I meant to test it last night, and got busy with other things. I will try again soon(-ish, after houseguests leave.) I did want to ask if the two-hour revocation window was what you wanted or just what you got working? On the day-job, I just finished converting a GitLab Enterprise OAuth app to a GitHub one, and, although we chose not to use them, we did investigate using refresh tokens. If we want to consider that here, let me know, and I might be able to pitch in. But to use them, we would probably want to be able to distinguish an active session from one that’s just not been closed, and I’m not sure what TW has for that. (I suppose the save hook would probably do, but there might be something better.)

#7

Ah, unfortunate. I will have to investigate what would be required to use a tiddlywiki.com sub-domain for this Cloudflare worker, and what sub-domain we might be able to use.

This was actually intentional to avoid the need to securely save the refresh token and further ameliorate concerns from users in terms of security.

In the current flow, you only need to be signed in when submitting or loading a PR, and if you have been logged out in the interim you can log back in without losing your work. So I am not sure how much we would gain in terms of user experience if we did decide to refresh the login session based on user activity. However, thank you for the willingness to help where possible.

1 Like
#8

Because I hadn’t been able to test yet, I wasn’t sure about that. But since this is the case, then, yes, there’s no great reason for refresh tokens.

Thank you for this, and all the great work you do.

1 Like
#9

@saqimtiaz … Thx for the additional info. I did update the OP with your info.

#10

I do use the pr-maker quite a bit and the 2 hour limit as it is at the moment is quite handy. For “smaller” changes it is OK and even works for 2 or 3 of them. Including extensive testing if needed

If I get distracted, it logs out without invalidating already changed tiddlers. So signing in and submitting a PR – Just works.

2 Likes