Proposal for GitHub workflow to allow for discussion and specification and final pull request

[twMat]

The following came up in a totally other issue ( #1223) - and that is what it concerns; that issues easily diverge into other topics, at least for some of us (who? me?)

The thing is; the current expectation that you ideally should be very focussed in github is not good for creativity and probably has a "censorship" effect on ideas.

@tobibeer noted that:

I think it's ok to discuss here and I think that's what Jeremy uses the "discussion" tag for. So, I'd leave it up for him to decide on preferences about that. The thing about "discussions" is, though, (when) will they ever get closed? It's hard to tell. Nobody will read through 20 long posts to figure out if there are any actionable items left, I guess.

I agree and here are some thoughts.

Maybe someone ( @Jermolene ?) can modify the github interface and introduce a new "category" like issues and pulls? Perhaps something in between like: "defined proposal", or fuzzier than issues like "discussion"...

Sorry if "modify github" is just preposterous to suggest - I don't really know what rights/settings/ powers a github user/moderator has.

However, the term "issues" is very fuzzy, indicating that this is in fact where you should have discussions... which then would mean pulls are for the defined proposal... which may then mean we take pulls too seriously? ...and they should be treated more as a specification rather than something that can be pulled, and maybe that thread could instead end up in an actuall code to be inserted? I.e a new workflow.

Is it possible to "delegate" a pull request that, in spite of all, freaked out to instead be an issue ?

...or maybe another workflow:

Thanks to the very smooth editing possibilities here, we could decide that the initial post is to be updated into a specification that can eventually be converted into a pull request. When worthy stuff comes up in the following discussions, it is merged into the top post. The difficult bit is that it would rely on the original poster to do so and to keep track on the issue. The ideal, for this suggestion, would be if there was a openly editable top post (...hm, why do all needs end up like a wiki?).

If a discussion participant identifies a portion he or she thinks ought to be included then s/he can mark it out in his own posts. Perhaps different font color.

This would probably also make spinoff ideas easier to split out into new issue threads.

...or:

If anyone could label a discussion. It could switch status by having anyone label it. It starts off, perhaps as an attempted specification but it turns into a fuzzy discussion anyway so anyone labels it "Discussion". Should someone what to really not have any discussion then I guess he could label it as such ("Specification" or even "No discussion"?) and were someone to want to discuss things anyway, then a new issue can be started. In fact, maybe two parallel issues could compensate for the wiki idea above; one titled [Spec] Change X into Y and the other [Discussion] Change X into Y. Posts in the spec would really only contribute to specifying, it's not a discussion really. Misbehaviour results in whipping over the fingers (now that should make all of us think twice!)

[tobibeer]

which may then mean we take pulls too seriously? and they should be treated more as a specification rather than something that can be pulled

Pull requests are actually how new code gets into TiddlyWiki. So, not sure if that' a good place. Also, the workflow may be more difficult rather than just creating an issue.

~

Theoretically, there could be a well structured folder for specifications and, as a "conceptual contributor", you may dare make pull requests on specifications rather than actual code, if only by inserting comments and quotes to be discussed / merged / amended by others.

~

Another option might be to create issues in your very own TiddlyWiki repo, if only an empty placeholder by that name. From there, you could @ mention the users you want to involve. I know, this doesn't have the same reach, so it may limit exposure of a topic... but it could be a workflow to discuss certain ideas in a given group first and then promote the outcome to actionable issues here.

~

Yet another approach may be — not sure if possible — to tag all new issues as "discussion" by default (automagically) ...and only if removed, you're sure it's an actionable thing / in an actionable status.

[pmario]

The existing github "workflow" creates an issue in 2 different ways.

• A user creates an issue, because a TW feature doesn't work. .. At least the user thinks, something doesn't work. ..
  • Such issues should be short and actionable.
  • Such issues should contain a description, how to reproduce the behaviour
  • Info about the expected behaviour
  • Info about the actual behaviour

While it is possible to "discuss" with github issues, imo it isn't designed to be a discussion board. eg: If you close an issue it is moved to the archive section of the UI and adding comments to archived issues is kind of wasted, because the thread is closed.

If you want to trigger a new action, you can create a new issue and reference the old one.

• If a developer creates a pull request, an issue with the same name is automatically created,
  • The pull request issue contains links to the code
  • It contains UI, that Jeremy can merge the dev code with his own code
  • It contains some info, if it is save to merge the code. ..
  • The issue should contain a detailed description of the new code and why it is important to include it into TW.

Pull requests are designed to discuss the "code" that is attached to the pull request. .. At the end of this discussion it is merged or rejected. ... In both cases the issue is closed.

If new problems come up in the discussion, a new issue can be created. ... It should be an actionable, short issue so it can be fixed and closed. If the code needs to be updated, the developer can push / add the new code to the existing pull request, until it is accepted or rejected.

---

A standard issue can not be converted to a pull request. A separate pull request can be created, that mentions and / or closes the issue.

---

You can't directly change the github UI. I'm sure you can create an issue anywhere but you can't change the UI in the way you can change TW. :)

[tobibeer]

Yet another approach may be — not sure if possible — to tag all new issues as "discussion" by default (automagically) ...and only if removed, you're sure it's an actionable thing / in an actionable status.

Of course, the opposite approach would equally work... perhaps even better.

So long as an issue is untagged it is really not actionable, a mere discussion. Only by being tagged actionable it is flagged for a dev, e.g. Jeremy or others making pull requests on the core code or documentation, to pick it up and work on it. That, however, requires a certain discipline and oversight as to which features or bugs to work on.

Something I very much find missing in GitHub are abilities to...

• vote on issues
• sort the backlog so as to express a development preference as to what to work on next

[twMat]

@pmario

The workflow you lay out does in deed not permit for discussion, as far as I can tell. But from the ideas Tobias and I mention here, do you not see anything that might work? Work better than currently that is. (Or maybe you don't agree with the OP?).

Still, @Jermolene has at quite a few times informally proposed to replace google dev group with github. Anybody knows how that would then work? Or would we then have discussions on the (general) google forum and only "short and actionable" only on github? I think dev discussions on the general board is not good and I don't think this is what Jeremy meant so it will be interesting to hopefully hear his thoughts on this.

@tobibeer ,

So long as an issue is untagged it is really not actionable, a mere discussion

Of your suggestions I think this one is the best. This would also mean that before it is labeled actionalbe someone must kind of sum it up. It is obvious that in some threads we need a summary regardless. This would just make us a bit more aware of this fact and it would make it easier for anyone not interested in discussions, but merely in actionable things, to find these. And if, in spite of all, it does provoke further discussion then it is simply a matter of removing the "actionable label". We must consider that discussion takes place because it is thought to contribute/improve on the matter (at least that's the premise). Anybody not interested in discussions can then filter on the label.

Anobody knows if @Jermolene has rights to give out rights to specific individuals so they can flag issues? I think it should not depend 100% on him to flag on this particular matter.

[twMat]

vote on issues sort the backlog so as to express a development preference as to what to work on next

Agree 100% There is no way to differentiate between great suggestions and less great ones. Just the other day I actually registered http://polls.tiddlyspot.com/ (nothing there yet) with the vague intention of a place for the community to express their opinion on things... but, as usual, it lacks the possibility to make something TW based, as opposed to embedded external services, where people can add input. I'm hoping an eventual federated system with some kind of individual ID can be used for this....

...however, it just strikes me that maybe tw.org could be used for this? @tobibeer ?

[tobibeer]

however, it just strikes me that maybe tw.org could be used for this?

As it is now, I don't think it's a good idea. Once we get it to being a collaborative ground for TW5 we can think of ways of implementing voting... and where to store votes in a user's space as a form of reply under some system-namespace maybe, e.g. $:/talk/votes/@space-voted-at/TiddlerName... containing the vote result having some field set to point to @space-voted-at and maybe a tag of vote ...so as to make TiddlyWeb query things efficiently.

[pmario]

The workflow you lay out does in deed not permit for discussion, as far as I can tell.

I think it works, but it's not very engaging.

But from the ideas Tobias and I mention here, do you not see anything that might work? Work better than currently that is. (Or maybe you don't agree with the OP?).

I think it's not intended to be a general purpose discussion forum. ... It works well for issues and issue archives. ... but imo issue threads are "throw away" threads. .. Once fixed / closed, they don't have much value anymore, because they are outdated.

[pmario]

Still, @Jermolene has at quite a few times informally proposed to replace google dev group with github. Anybody knows how that would then work?

It won't.

I think you did misunderstand Jeremy's statements here. He proposed, to move some development discussion from TW-dev group to github but github should not replace the google groups, because it can't ... we don't have a replacement for the groups at the moment.

[twMat]

I think it's not intended to be a general purpose discussion forum. ... It works well for issues and issue archives. ... but imo issue threads are "throw away" threads. .. Once fixed / closed, they don't have much value anymore, because they are outdated.

You're probably right, but the question remains how we then should discuss issues. From what I've seen, I think it is obvious the proposals have very often been improved thanks to the discussion. But maybe they should simply be in the google dev group? Is that you opinion Mario?

So those who know about this debacle, and who want to of course, could first post their issue on the board to get input on it. and then copy any conclusion to here.... Doesn't seem like a practical idea though... the idea of relying on people copy-pasting stuff, hmm...

Having ideas bounce around in the form of discussion is probably the most effective tool for having ideas mature to full potential (even if you obviously never know). Considering we're discussing a problem for development of TW, if ever there was a crucial activity, just maybe we have, after over a decade, come to a point where we should "eat our own dog food" (to use Rick Shumakers expression). I.e to actually build the perfect communication and development tool for TW. I don't see us adopting another discussion forum or software, at least not until google shuts down the boards. And if github isn't really spot on for optimal development in TW then... the time might just be here. What are actually the bottlenecks for this? Competence? Money? Too few Jeremys? ;-)

[tobibeer]

I think it's not intended to be a general purpose discussion forum.

That's not quite the point. The question is, does it work well when used as one.

It works well for issues and issue archives.

Indeed.

but imo issue threads are "throw away" threads. .. Once fixed / closed, they don't have much value anymore, because they are outdated.

As far as I can see, they're pretty much accessible. The one problem I see is that the actual repo-issues get cluttered with tons of discussion issues... which totally distracts from coming to terms with what to code ...and what was coded.

So, perhaps, a dummy repo for the sole purpose of discussing things may be helpful... or that approach of tagging issues "actionable".

[tobibeer]

So those who know about this debacle, and who want to of course, could first post their issue on the board to get input on it. and then copy any conclusion to here.... Doesn't seem like a practical idea though... the idea of relying on people copy-pasting stuff, hmm.

It's reliable, you also get those neat references.

As I said, I can well imagine an actual spec repo ...one that holds specifications that make up the content, instead of code. Once that collaboratively evolving spec is mature, you can derive actionable issues.

People would work on those specs for whichever topic(s), fork, modify, merge... whatever. Someone would have to have a hand over it, not sure how to make a number of people able to manage such a repo.

[pmario]

@twMat ... Do you think this issue should stay open? ... We do have discussions now at github. They are not used that often. IMO talk.tiddlywiki.org has won the competition?

[twMat]

Yeah, I think the OP is obsolete now. Thanks @pmario