TiddlyWiki GitHub Repository Labels and their Meaning

Developers
#1

Hi Folks,

Some of you, who regularly visit the TW GitHub Repo will probably have seen, that the issues page and the pull request page are much more colourful now.

All the currently open issues have labels now. Those labels can be assigned manually by the repo maintainers. They should help us (the community) to easily sort / filter issues, to find out how to contribute.

image
image2556×1279 355 KB

Background

Some weeks ago @jeremyruston and I did sit down and discussed “the naming” and “the meaning” of those labels.

In the following weeks – till now – I did read and label all of the existing issues and most PRs.

Starting with 1100+ open issues and 200+ pending PRs.

Jeremy was able to merge some of the valid pull requests. Some PRs had to be closed, because they where implemented in a different way. Almost halve of the pending PRs are work-in-progress aka draft at the moment.

I was able to resolve quite a view of the pending issues. So we are down to 880 now and all of them are labelled.

Starting Point for Contributors

  • Issues labelled documentation are good starting points for contributors which are “cool” with TW wikitext

  • Issues marked actionable and basic are good starting points for new contributors, who can help with HTML, CSS and JavaScript code

Important

  • Basic complexity does not mean trivial. It means “low risk” to cause backwards compatibility problems
  • If you want to start a new PR for an issue, make sure it has an actionable label

How to get an actionable label

Pull requests have a higher chance to be merged, if the related issues is actionable.

If an issue has no actionable label yet, but you are interested to help, or you are interested in the “feature”, you will need to kick of or restart the discussion again.

Label explanation

The following list is alphabetically sorted.

There is a GH issue: [TEST] all labels - and describe them · Issue #9399 · TiddlyWiki/TiddlyWiki5 · GitHub that has all labels assigned, so it will show up in every filter. It contains the same info that will follow here, as a reference. The text in the GH issue is the “source of truth”.

actionable

That’s the goal!

  • Issues with the actionable label, should be possible to create a PR
  • Discussion that came to an actionable conclusion
  • If Jeremy or an other maintainer explicitly asks for a PR
  • If possible maintainers give it a “basic” or “advanced” label

actionable:code

  • Same as actionable
  • This issue also contains some (tested) code snippets, that may help contributors to work with
  • Especially issues created by Eric Shulman work that way

advanced

  • Advanced complexity
  • Risk of compatibility problems

basic

  • Basic complexity
  • Low risk of backwards compatibility problems

bug

We want to get rid of them :wink:

  • Issue, that can be replicated, can be considered a bug eg:
    • Performance regression
    • Functionality regression
    • RSOD
  • Has to be acknowledged as a bug by a maintainer
  • Bugs should get high priority - Help / PRs are very welcome

compatibility

  • Most likely breaks backwards compatibility
  • Considered advanced difficulty
  • PRs marked with “compatibility” label will require patience from the contributor
  • May “move” in a frustratingly low pace – but from time to time we will need them

discussion

  • If the OP (original post) is not actionable yet – and
  • There are 5-10 posts argumenting back and forth, the issue is considered a discussion
  • If a discussion also has an actionable label, it should be possible to create a PR
  • A discussion can be about an improvement, newfeature, refactor – If it gets an actionable label
  • If there is a long discussion, it can be considered “advanced” complexity

documentation

improvement

  • Existing functionality, that can / should be improved
  • Considered “basic” or “medium” complexity
  • Improvements should not trigger a compatibility label
    • If they do, they should be labelled “refactor” instead (improvement is removed)

native:app

  • These issues discuss problems with 3rd party native apps, which may also need some work to be done with TW

needswork

  • Issue that is not actionable at the moment
    • Feedback from the issue creator is needed
  • PR that needs more work to be merged.
    • Eg: Merge conflicts need to be resolved.

newfeature

  • New functionality that does not exist at the moment
  • Considered “basic” to “advanced” complexity
  • Can have “compatibility” label

pluginise

  • Functionality, that should be part of a plugin
    • core plugin or
    • 3rd party plugin

refactor

  • Usually, quite some work has to be invested
  • Is considered advanced complexity
  • Needs to take backwards compatibility into account from the beginning
  • Can be slow

usability

  • Issues that may change or improve the user workflow
  • Used mainly in combination with issues labelled “discussion” and “improvement”

usability:a11y (accessibility)

  • Issues that may improve accessibility for users using assistive tools
  • Also see: usability

admin-review

  • Admin marker for issues that should be reviewed again
    • needs a new label
    • has no label yet

Information here will be updated in the future. But for the start – that’s it.

Have fun!
Mario

4 Likes
#2

How to Filter for a Label

  • Every label is clickable.
  • If a label is clicked, the value will be inserted in to the text input field as shown in the screenshot

image
image2370×591 127 KB

  • If you want to add a label to the filter you can
  • Directly write the text: label: followed by the first character of the label you want (see secreenshot)
  • A dropdown will be shown, which you can use to finish the second label eg: basic

image
image2370×629 170 KB

So it will list all actionable and basic issues

image
image2383×929 309 KB

#3

Pinned to Developers category for 2 months

#4

Good work! I did notice the number of open things coming down.

One question:
What is the distinction between bug as a label and bug as an issue type please, in terms of how TiddlyWiki uses them?

bug as type v bug as label
bug as type v bug as label1267×384 38.3 KB

#5

Thank you both. This is fantastic!

#6

The one you marked is created automatically, when an issue is created. The name will most likely be changed in the future. Bugs have to be reproducible issues, that are regressions or software defects. They have to be verified as bugs by maintainers.

#7

A post was split to a new topic: Why is one of 2 similar issues at GH marked as “not planned” and the other as “new feature”

#8

bug and feature issue types now seems to be problematic for maintainence, related issue: [BUG] type test using Idea template · Issue #9492 · TiddlyWiki/TiddlyWiki5 · GitHub

There is a pending PR that change issue types to reportand idea: New issue and bug report templates by pmario · Pull Request #9512 · TiddlyWiki/TiddlyWiki5 · GitHub

#9

Just thinking further on this, if you are open to a couple more tweaks to make things a bit more immediately obvious to someone who hasn’t seen this forum topic.

  1. It isn’t entirely obvious what bug means, and perhaps it would be better stated as bug-verified or something to that effect.
  2. Likewise, compatibility could be termed compatibility-break to make it clear upfront what it means

The purpose of these suggestions is so you know exactly what these mean even if you aren’t a community regular who would be reading this topic - as labels are for the benefit of users as much as maintainers.

  1. needswork could definitely be useful - I would just highlight that there is metadata that GitHub offers which you may be using to track this already.

    Maybe there is scope for automation here for example, e.g. if a reviewer requests changes, then needswork is automatically applied. When the changes are approved or a collaborator withdraws their review, then the label automatically removed.
#10

By the way, I think it would be worth

  • Re-naming this topic for SEO & clarity purposes as long-term really about labels used on the issue tracker.
    In the more immediate term though, I want to again praise your tremendous effort in triaging and categorising open issues and pull requests.
  • Integrating this guidance onto other places if it isn’t already, e.g.
    • One of the tiddlers on TiddlyWiki.com, probably a new one linked from Contributing and ReportingBugs, so people know can look up why a maintainer applied a specific label.
    • On GitHub itself, perhaps, if curious users would be likely to look there? Again, may be better as a link to the relevant tiddlywiki.com tiddler.

It’s also a rare chance to use WikiText syntax for description lists, which to date, I have not seen even once in the wild. :laughing:

#11

Will open PR be annoying? I sometimes quickly create a prototype PR, and may leave it for months to play with other things. When I come back, the maintainer comment may already placed cold.

Maybe I should convert all of them to draft PR, until I want to revisit them.

And due to I have copilot pro+ subscription, I tend to create PR directly instead of issue, because the effort is only basically the twice, and showing code can be more clear for discuss. Due to natural language limit, old issues may cause long discussion and still leave confusion.

And thanks for reviewing PRs @pmario aka @Mario

#12

Hear, hear! This was clearly a heroic effort.

Interesting, as I use them all the time. But I have a lot of data-heavy wikis, with templates that do little more than show important field values.

#13

There are different views about open PRs. — I think, since drafts exist it is much better, since they clearly “state” that a PR is still a work in progress.

The biggest disadvantage of how GH handles PRs is, that changes to the same file with 2 different PRs always invalidates one of them. So they have to be fixed by contributors, which can be quite annoying.

I did mark PRs with “merge conflicts” with the “needswork” label. … So needswork is a marker for contributors and also for moderators, that have a look from time to time.

That’s perfectly fine to create prototypes. Since we have the auto-preview creation it’s nice to be able to also test drafts with a real preview-wiki.

There will definitely be more comments on “open for review” PRs, than on WIPs. From time to time I also comment on WIPs, if something catches my intention.

IMO if you consider something a WIP, it would be nice to convert it into a draft.

#14

If something is labelled “bug” it should be verified by a maintainer or an other user. There are a view issues marked as “bug”, where I was not 100% sure – but I thought it is important enough to get high priority attention.

I think compatibility-break also is not 100% right. Even if something is labelled “compatibility” the merged implementation may be backwards compatible, if we found a solution to keep it compatible.

So it mainly is a marker for contributors, to be patient and for maintainers to be extra careful while implementing and testing.

#15

You are right. needswork and also admin-review also are meta labels, that may be improved in the future.

Initially “needswork” was only used for exiting PRs with eg: merge conflicts or comments from Jeremy, that something needs to be implemented differently.

But while working through the issues, I also found out, that some feature request issues could benefit from a “needswork”. Where it means “with a bit of more thoughts” it could be made “actionable”.