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