There is a bureaucratic necessity. … The CLA (Contributor License Agreement), which has to be signed by contributors. …
I know that this is an additional hurdle, but if someone did sign the CLA, they did create a PR against the master branch. … So if your first PR is merged, the workflow should be easier for the second one. … and so on
I’m also learnign it now. I have a two handicap with: the language and my “memory”.
For this I prefer the intructions with listed (short) steps. It can have introduction/description/etc. So I can easily see what was the last done step.
I have also discovered the problem of the conflicts. In my case when I have worked in an not updated branch and the master branch has changes in one of files which I modify in my PR. I have to learn how I can avoid it. In other words, I think that it would be that I don’t work in the lastest commit where the files of my PR have/had been modified.
Documentation via github is massively complicated. And it is made even more challenging by the “improvement” where everything goes under a separate branch. The documentation for this change consists of a SINGLE LINE (and yes, I am yelling because that is how I feel about it!).
If you already know GitHub, note that documentation updates must be directed to the
tiddlywiki-combranch
That’s it! What does “directed to” mean? How is it supposed to work? Why is anyone expected to know this? Shouldn’t there be at least a paragraph to explain how this works? And yes, maybe I should write it.
At this point, you’re having to push a sub-branch of a branch of a repository to a sub-branch of a branch of a fork of an upstream. And then the PR needs to be re-navigated to sync with the tiddlywiki-com branch. This is something that you will have a hard time even googling, because every google results in hundreds of answers to normal, regular github questions.
Does anyone really think this is reasonable?
And if you want to keep your local working repository in sync with the master, you’re going to have to know about fetch and merge on sub-branches, and once again all the standard stuff you find on Google will be inadequate.
If Github would let me, I would just make a different fork for every change I want to submit. That way everything would be up to date and almost simple. I would delete old forks and move on after the merge. But you can’t make a second fork.
Except they never had to make an offsite repository for that. And they had to make a tiny, simple text change. But if you’re going to make extensive changes, and don’t want to have it riddled with errors, you’re going to need your own local repository.
Oh, and now GH wants you to use a passcode instead of a password. Big long thing that you either need to paste in every time or write a script to insert.
You shouldn’t have to be a Github guru to submit documentation changes!
The things you pointed out are absolutely challenges and why it’s hard to move on editing documentation over time. If there is a goal of broader, non-developer participation in documentation improvements and maintenance, we as a community will have to work on this.
They are called branches, and you can do this. In fact, I just checked, and it does this by default:
This is me editing the readme file, and as you can see it is telling me it will create a new branch in my existing fork.
Your point still stands! Doing PRs that target a particular branch is a whole thing, but it’s a slippery slope to fully explaining how git works – and I don’t think teaching non-software-developers git is a useful path. It’s up to us to make this easier at other levels.
Hear bloody hear.
I started a little while back, jumped through the hoops (aided by @saqimtiaz - thanks Saq) then completely stopped. Life (mine, anyway) is far too short to waste it on that rigmarole.
My (not so) humble opinion…
@jeremyruston does a fantastic job of “policing” the code base – I have no issue there (nor do I participate, either). That is a key role and must be fostered and adhered to. But the docs? It’s a wiki, for crying out loud! I’d have no issue at all with some kind of clearing house/central control – which is what I think (strongly believe) Git allows.
But GitHub?
It’s insanely complicated. I’m no spring chicken, got the coding battle scars to prove it – but this is one war I don’t need to fight. The gaps between me doing something in the docs would mean keeping extensive notes (which I may or may not understand next time). The moment you take notes, you open another door: keeping the notes maintained. No thanks.
This woulda/coulda been my way of giving back – feels like the system said “no thanks”.
Github is git underneath, and unfortunately git by itself wouldn’t make this any easier, just less / different UI.
My ideas aren’t fully baked here, but I think something like using a tw.com download and the GitHub saver, or just documenting steps for running this on nodejs locally and committing to your own fork could be possible. Merging / PRs may still need to be done by git experts.
I think, like @markkerrigan’s suggestion of creating a documentation category, this is a “top level” community project. I suggested in that other thread:
So, who wants to work on this? Who wants to help improve documentation and be part of the Documentation contributors group?
Of course. Don’t teach grandpa to suck eggs 
Like I said, I’m no spring chicken.
But I’ve learnt that thick skins drawn over bare-metal commands can obscure the fundamentals to such a degree that sometimes they don’t help – they confuse. Having learnt that, I choose not to be confused. I did enough to prove it was a taxing task (for something that was inherently simplistic) and promptly did something far more constructive, instead.
Yes, I saw your posts. Good idea (I think). 
No! No! No! Branches are NOT the same as forks. When I fork, I know everything is up to date. When I fetch and merge, I always have the feeling something is going to break, especially since it’s so poorly documented. (I mean, the Github stuff isn’t well documented beyond the very basics).
Even the Github CLI doesn’t give a good tool for viewing sub-branches. All the documentation is in terms of one-branch (usually main) and some very temporary working branch.
I want to start with a clean slate. Not be worried that a change I’m making is going to go to the wrong place and overwrite good stuff.
Once again, you’re working in a repository on a branch that’s a sub-branch of a branch that’s on a repository of fork of a project, and none of the documentation explains clearly what you do to fetch or pull in order to keep your site up to date. Try finding the documentation that explains that exact scenario!
To the casual user of Github, it’s a nightmare. Like I made some updates last month, but had to spend a half day reviewing because my last usage was in March. Conceptually, it would be easier to make a half dozen GH accounts and have a fork for each submission!
Wikipedia became the most successful encyclopedia on the planet because they made it easy to participate. It’s ironic that the documentation for a wiki can not be made as simply.
Branches is the common industry way to do this, with various techniques on how to update your branch / fork, which is most definitely out of scope of this thread – because that’s all targeted at software development of code, not documentation.
I don’t know what you mean by sub-branches, that’s not a thing in git or Github.
Again, I agree with you, and “casual user of Github” is a terrible experience.
We’re doing a very good job of highlighting that IF more documentation is desired, someone in the community is going to need to propose & work on some ways to improve this.
Do you have any suggestions?
Thanks @boris for tagging me here. I just want to chime in that unless you’re a GitHub expert, the process of doing the PR and forks can feel rather tedious.
I had helped a bit on the TiddlyWikiClassic documentation so I’m familiar with editing the .tid files and submitting the PR but I’m not a regular developer so it’s not in my muscle memory. But it’s easy to run out of steam on that. Simplifying the TiddlyWiki.com documentation process has been discussed before, but it seems like the process is still the same.
My thought on creating the Documentation Category is to have a singular place for discussions about documentation to exist. There are over 800 issues on the TiddlyWiki and this one about documentation, but it’s only likely to seen by people who are actively involved in following the GitHub. Also probably a more aggressive step would be simply to close all the issues related to documentation and direct those communications to the Discourse channel and people can submit PR when they have their actual fixes ready. Alternately someone can suggest improvements in the Discourse channel and someone who is GitHub savy can submit the PR.
Maybe this is considered off-topic, but documentation is one of the reasons I’m so interested in multi-user TiddlyWiki development. If TiddlyWiki.com had functionality like Wikipedia.org where anyone can edit it inline, it seems like a lot of barriers would be lowered. I think DocuWiki has something like that too… not 100% sure.
Well, yes OT in that we’re now trying to figure out improvements / solutions
But you’re right — running TW.com in multi user mode could be a solution to improving docs flow.
This is totally doable!
“Somebody” has to stick up their hand and volunteer to organize a Documentation group.
I might just split parts of this thread back into Mark’s post?
I’m not opposed to creating a dedicated category — but for a category like this I’d like to also scale the responsibility. If three people say “I’ll help”, I can make a Docs group and away you go in figuring it out. Who wants to run with this?
You should. (plus more needless but obligatory characters)
Wow: as a naive user of Github (in single-user mode), i had no idea all this branching/ merging stuff was so complicated! Considering this, i resonate most strongly w/ this comment:
YES indeed: Why can’t we do this collaborative documentation-building stuff in wiki? Clearly we can -examples all over the web abound- but doing it in TIDDLYwiki seems like a big hairy challenge, because the technology architecture does not lend itself easily to multi-contributor workflows… And doing it in some other flavor of tech, like MediaWiki or such, would be like a confession of our own inadequacy. Is that a fair statement of the problem?
If it is, then i’d be inclined to let go of tech bias for a bit (at least until one of those multi-user TW development initiatives i’ve heard bandied about yields production-ready fruit), and consider a fork of some proven solution to this problem.
Most obviously: Wikimedia Foundation has spawned a host of good examples -including Wikimedia Commons, a “gene bank” of resources that we might do well to integrate at a deeper level, i would say- and while all this is going on, our patron saint Ward Cunningham has not been standing still; his Smallest Federated Wiki project implements some very interesting ideas about how a wiki community might rip/mix/burn each others content in a most fruitful way. Still needs somebody(s) to edit & publish the canonical content-set in our particular UseCase… But as this is being done anyway (by @jeremyruston , i presume), what we’re talking about here is how that process might be made more efficient and/or effective by throwing the weight of a wiki-powered community behind it.
I don’t expect there’s anything new in what i’m saying for all you veteran wiki-weavers… Yet perhaps the idea of using wiki-tech to build better docs in a more collaborative way is one whose time has come (?) If so, then i’d be happy to contribute to that effort.
/walt
The problem is that the current GitHub based flow is too complex and this blocks further participation.
The second problem is no one is volunteering to spend time figuring out if a different TW flow is possible by owning the issue with a group of 2-3 people to start.
That’s not me “pointing fingers” just pointing out that there doesn’t appear to be enough bandwidth in the community.
At the moment TW is a “mono-repo” where it is impossible to give different groups of users access to different elements of the repo.
IMO you have to convince Jeremy, to split the repo into elements that can be handled by different groups. … As long as we have a mono-repo, we will have to stay with the status quo.
The mono-repo and permissions is a challenge to some possible improvements. Branches, GitHub Savers, TW on NodeJS for editing, GitHub Actions, etc might be some tools that could help improve things. I don’t know, I don’t have time to invest in investigating further at the moment either.
To convince Jeremy of anything, someone will need to do some research and suggest solutions.
Firstly, without @jeremyruston’s agreement that “something needs to be done”, I’m not sure investing in a POC, theoretical or practical, is worth anyone’s effort.
Agreed, though perhaps “blocks” is too strong a word? The system is fine for people that spend half their dev/work time in GitHub on a regular basis. For others, it’s a hindrance at least – the on ramp too steep/too time costly, especially if what you’re trying to do is a quick/minor change to the wording. Yeah, perhaps “blocks” is the right word
Agreed. tw.com is not Tiddlywiki. tw.com is an instance of Tiddlywiki. The “docs tiddlers” should be something else entirely.
I honestly don’t know where this topic is going 
Surely we could keep the docs tiddlers in a separate repo, but have a workflow that automatically merges changes discovered there into the main repo? (We might also need to back-propagate changes from the main repo into the separate repo, but that’s no big deal either.) IIRC we are already doing essentially that with the Links Aggregator (indeed, that workflow is a little more complicated since it has to do something with each of the repos it pulls, and any number of users can have their own repos). I was the lead on Azure DevOps pipelines (very similar to GitHub Actions) at my last job for several years, and my experience is you can make basically anything happen as long as you have a clear picture of what you want. The only challenge here would be merge conflicts.
If the problem is basically that there are too many buttons to click in GitHub, this would seem to solve that problem. Fork docs repo, clone to computer, run tiddlywiki --listen, make changes, push changes, PR to docs repo.
Obviously it would be nice for participation if we could edit directly on the web, but that would be a start, and pretty easy to implement.
Maybe Jeremy wants all the doc PRs to be within the same repo, though? That would be the only thing blocking this kind of a workflow as far as I can see. I’m not sure how important that is, though – the benefit is being able to see changes to the docs made in the same commit as changes to the code, but nothing in this workflow would preclude being able to do that, we’d just also have the option of making improvements to the docs unrelated to any code change in a more convenient way.
This is the kind of “let’s figure it out” process that some group of people need to take ownership of.
Are you interested in taking this on @sobjornstad?
