Could we simplify the PR process?

twMat · January 30, 2022, 2:20pm

In another thread it was proposed to make a PR for a small matter, i.e a “pull request” which is when you make an improvement to TW and request that it is included.

Documentation PR’s are simple to make (but definitely awkward because of the github workflow), i.e: In tiddlywiki .com you click to edit the doc tiddler and the seen pink strip has a link to edit the tiddler on github. This assumes you have a gh account.

Code PR’s are another matter… and it is just sooo awkward. This is my typical “workflow” before giving up. Where do I go wrong?:

On tw .com I locate the relevant tiddler e.g this.
Since there is no link to gh in edit view, I search for it on gh —> no result (Why?)
For the n’th time I youtube how to make a gh PR. Thousands of results. Start watching one… “In the terminal window”… eh, why? For doc tids I can do it directly in gh. And those “git push origin” commands - I don’t want to spend X hours learning magic commands. OR “Just click on the file in gh” - exactly, but I can’t find it in the repository to begin with!?

During this I have a nagging feeling that I won’t succeed even if I would manage to jump through the many hoops. I understand that it is ME that is at fault here since everyone else in codiverse loves using gh. If I took a course on it, or if my salary depended on it, I would spend hours swearing and probably eventually learn it. But, for now the end result remains: I again conclude that I won’t do non-doc PR’s. Perhaps that is not a big loss for the community but I suspect I’m not alone in reasoning like this - and that IS potentially a big loss!

So… could the process to make PRs just be much simplified for non-github users? Or does it have to be this weird?

Here’s one idea:

It is only the very “posting of the PR” that needs a better solution. So make it so you can modify tiddlers on tw .com and send it “somewhere”. There could be a receiving script that converts it into a real gh PR for review. The user could, maybe in the edited tiddler on tw .com, get back a link to the actual gh PR so he/she can follow it if so desired.

A main point is that users are already familiar with the TW UI.

telumire · January 30, 2022, 2:52pm

Usually you can find them by searching title:title-of-tiddler with the option “In this repository”, or with the url https://github.com/Jermolene/TiddlyWiki5/search?q=title:title-of-tiddler

E.g :

https://github.com/Jermolene/TiddlyWiki5/search?q=title:$:/config/AutoSave

But I agree that it would be great to link to this with the ribbon

“Can you help us improve this documentation? Find out how to edit this tiddler on GitHub”

EDIT: hum you’re right, I dont find the tiddler you quoted with the search … maybe it’s generated procedurally ?

Same results with the advanced search : GitHub · Where software is built

jeremyruston · January 30, 2022, 4:48pm

The PR-based development process is almost universal amongst open source projects. That’s really crucial: we’re not in the business of inventing new ways for open source projects to run. A small community like ours can only exist by riding on the shoulders of all the other open source projects, and doing things in broadly the same way. The sharing philosophy that we see within our own community also exists at a higher level, with communities of communities sharing tools and processes.

So, I think it’s important to cast this not as a problem that is unique to our community, but one that is shared with other projects. That’s important because we have little choice but to build our own infrastructure for things that are unique to our project. But it’s not economic for us to build infrastructure for problems that are universal to all (or most) projects.

That means that to solve this I think we need to look outside of our own project, and explore what solutions other projects use.

I know that many projects, for instance, make it super-easy to spin up an instance of the project on services like https://sandbox.io/. If things are set up correctly, forking the code and getting it up in an editor is a one click operation. It is possible for users to create a PR with their changes, but it is also possible for somebody else to do that for them.

anon9140225 · January 30, 2022, 5:07pm

The file you are looking for is

github.com

Jermolene/TiddlyWiki5/blob/d455072f13dd00955ae82d62d2d6e44581bdba9e/core/language/en-GB/Misc.multids

title: $:/language/

AboveStory/ClassicPlugin/Warning: It looks like you are trying to load a plugin designed for ~TiddlyWiki Classic. Please note that [[these plugins do not work with TiddlyWiki version 5.x.x|https://tiddlywiki.com/#TiddlyWikiClassic]]. ~TiddlyWiki Classic plugins detected:
BinaryWarning/Prompt: This tiddler contains binary data
ClassicWarning/Hint: This tiddler is written in TiddlyWiki Classic wiki text format, which is not fully compatible with TiddlyWiki version 5. See https://tiddlywiki.com/static/Upgrading.html for more details.
ClassicWarning/Upgrade/Caption: upgrade
CloseAll/Button: close all
ColourPicker/Recent: Recent:
ConfirmCancelTiddler: Do you wish to discard changes to the tiddler "<$text text=<<title>>/>"?
ConfirmDeleteTiddler: Do you wish to delete the tiddler "<$text text=<<title>>/>"?
ConfirmOverwriteTiddler: Do you wish to overwrite the tiddler "<$text text=<<title>>/>"?
ConfirmEditShadowTiddler: You are about to edit a ShadowTiddler. Any changes will override the default system making future upgrades non-trivial. Are you sure you want to edit "<$text text=<<title>>/>"?
ConfirmAction: Do you wish to proceed?
Count: count
DefaultNewTiddlerTitle: New Tiddler
Diffs/CountMessage: <<diff-count>> differences
DropMessage: Drop here (or use the 'Escape' key to cancel)
Encryption/Cancel: Cancel
Encryption/ConfirmClearPassword: Do you wish to clear the password? This will remove the encryption applied when saving this wiki
Encryption/PromptSetPassword: Set a new password for this TiddlyWiki

This file has been truncated. show original

anon9140225 · January 30, 2022, 6:37pm

For the benefit of others, I am documenting the workflow to create PR without using terminal

Assuming that you have a

Preparation

If you do not have a GitHub account, create one and log in.
Go to Jermolene/Tiddlywiki5 and create a fork of TiddlyWiki5 repository.

Github01914×308 66.4 KB

You only need to do this step ONCE in your life time. If you have previously forked TiddlyWiki5 repository, see point 6

Creating a PR in 5 steps

Find the file you want to edit in your fork. Click on Go to file and start typing the title of tiddler.

Github11635×469 71.1 KB

If you cannot find the file this way, it usually means the tiddler you are looking for is a multid or generated by a script. In that case. Go to Jermolene/Tiddlywiki5 and paste a sentence or two from the text (not the title) of the tiddler, then click “search in this repository”. That will show you the path to file.
Edit the file in your fork. You can edit it in GitHub itself.

Github-Edit1618×483 60.3 KB
Once you are happy with the edits, save the changes by filling out the Commit Changes text boxes seen below the file you are editing. NOTE: Do NOT select the option Commit directly to master branch. Instead select Create a new branch option, and click propose changes.

Github21501×409 36.7 KB
Now come back to the main page of your fork. GitHub will automatically detect that you have made some changes and will ask you if you want to open a PR to the main TiddlyWiki5 repository. Click “Compare & pull request”

Github31854×525 79.4 KB
Fill out the form appropriately and click “Create pull request”

Now after a long time you want to create another PR. This time, instead of forking again, you can go to your existing fork and simply click “Fetch upstream changes”

Github-Fetch-Upstream1635×469 71.4 KB

The Good habits

Once Jeremy reviews your PR, he will either merge it or will tell you why he cannot merge it. In the latter case, it is highly recommended/strongly urged to close your PR as soon as possible so that the pull request queue will not keep piling up. One less item for repository maintainers to worry about.
So a PR is either merged, or you have closed it. In both cases, GitHub will immediately ask you if you want to delete the branch from which you made the PR. It is a good habit to delete it.
Take care of white-spaces, indentations and other code formatting.

I will try to write up the terminal based workflow in Linux later.

Mark_S · January 30, 2022, 6:46pm

What if you have 2 files that need to be edited?

TW_Tones · January 31, 2022, 12:24am

I would just add I too find the PR difficult especially where more than one tiddler is involved.

I totally understand @twMat and his frustration. We should always take very seriously people complaints about difficulty contributing, because contribution’s is what drives tiddlywiki. However when it comes to change only devs experienced in GitHub seems to be able to contribute or at least others are discouraged to a point of abandonment (I for one fit in this category).

It is fine to choose GitHub as the repository and method in which to manage code change but I think it should be easy to build a layer on top, even if that needs minimal but necessary intervention by someone with git hub experience to trigger one or more PRs. I would volunteer, but I am not one of those yet.

telumire · January 31, 2022, 2:44am

Personally I would edit them on my (up to date) tiddlywiki, export in .tid and drag&drop over the forked github branch. Then fill up the PR, review the changes and edit the files on github if needed.

There is also the custom tiddlywiki edition by saqimtiaz, I dont know if it can still be used but the idea behind it is great : Edit documentation in TW and use Github API to create PRs directly?

Mark_S · January 31, 2022, 3:14am

Are we still talking about working with the GH interface? I didn’t know you could drag tiddlers/JSON onto the interface, but even if you can, how would GH know what to call the tiddlers? The exported file names may not be the same as the internal file names.

It works great for documentation! Not so sure how it would work on the master branch, with shadow/core tiddlers. The main problem with it is if your PR is not accepted. Then you’re back to using the regular command line interface. In my experience, submitted code almost always needs changes.

Or put a different way, anyone who is good enough to get code through the first time without requiring changes probably doesn’t need a PR submit form either.

telumire · January 31, 2022, 12:47pm

Yes I do this on github.com.

Add file > Upload files (or drag & drop)

You can drag and drop your file or use the file explorer (choose your file).

You can rename the files you drag&drop after the fact too, but then you need to edit your PR.

Files changed > … > Edit File

Then you can tweak the file, change the filename, etc

You can move the file up in the hierarchy from the filename field with the Backspace key (delete the text before the filename) or down with the Slash key.

Mark_S · January 31, 2022, 5:20pm

I know dark themes are trendy, and they’re better for hours of work. But for documentation, they’re a lot harder to read. And they’re murder on your toner ink if you print out.

telumire · February 2, 2022, 5:24pm

Out of genuine curiosity, and while I agree with you on the readability part - Are there really people that print out software documentation ?

Mark_S · February 2, 2022, 6:50pm

Ebooks are great for novels, but not so great for technical material. I really hoped by this time there would be large-screen, fast e-ink readers available.

DesertDwarf · February 2, 2022, 7:48pm

I like reading technical stuff on-screen. My main issue with paper is I can never find CTRL-F.

TW_Tones · February 2, 2022, 9:41pm

Perhaps cheat sheets or people who like to read on the toilet and don’t have a mobile/tablet which is now a diminishingly small number.