How do I get started as a new contributor?

Hey folks,

I want to make some accessibility contributions but don’t know how to get started. For background, I have quite a bit of experience and am familiar with working with Node/NPM-based projects. I just don’t quite know how to work with this one.

For starters, I want to add role="region" to the sidebar. I believe I tracked this back to core\ui\PageTemplate\sidebar.tid. I added role="region" to:

<$scrollable fallthrough="no" class="tc-sidebar-scrollable" role="region" >

And now I guess I need to edit core\modules\widgets\scrollable.js. I do, adding a check for the attribute and a console.log for good measure. But either I’ve edited the wrong files, or restarting the server via:

tiddlywiki editions/tw5-com-server --listen

is the wrong command or is missing a step.

Are there any developer docs I’ve missed? I’ve googled but haven’t found much. Also, I’ll need to restart quite a bit. Does anyone have a favorite setup for handling hot reload of changes? Or at least something to restart the server so I can refresh from the browser without having to switch between 3 windows?

Thanks.

Welcome to the club! :wink:

You are right. The attribute check has to be done in the $scrollable.js code.

Attributes are calculated in the .prototype.execute() function, where they are assigned to local object variables to keep them in the closure.

The DOM elements are created in the .render() function, where you can add the role, to one of the elements. … You have to choose the right one. Looking at the code atm, scrollable seems to create 2 DIVs … So a bit of testing needs to be done.

The main TW concept is discussed at: https://tiddlywiki.com/dev/ … BUT there is no complete low level dev API docs. It mainly is the tests at: TiddlyWiki5/editions/test/tiddlers/tests at master · Jermolene/TiddlyWiki5 · GitHub and the source code.

We would absolutely appreciate help with this part of the docs.

I personally don’t mind to manually restart the server. It’s probably a second to switch between the browser, the terminal window, restart the server and switch back to the browser or VSCode. … BUT I would like to assist to create a more automated workflow.

The last time I did test an automatic “save code” – “restart server” – “reload the browser tab” mechanism, the node “file watch” functions where not reliable enough on Windows.

So if we create something, we need to make sure it works with Linux, MacOS, Windows and a nice to have would be the possibility to make it work with a Docker “server container” too.


I did clone the TiddlyWiki repo and made a “npm link”, so it always uses my active source branch to start tiddlywiki with tiddlywiki .\editions\tw5.com-server --listen … (So your command looks rigth :wink:

To start contributing, there also is a bit of bureaucracy.

See: https://tiddlywiki.com/#Contributing especially the CLA (contributor license agreement) section and How to sign the CLA.

2 Likes

Thanks! The npm link was the missing piece. I wasn’t sure how the JS in the repository was pulled into the build that got loaded in the server. I guess that’s loaded by the executable in the repo, which I just linked.

I have a first batch of changes ready to PR. Just a few more quick questions:

  1. Is there a place to add non-user-visible translatable strings" I have an aria-label="Sidebar" on the sidebar region to indicate to screen readers what it is. This isn’t a button. Guessing Misc.multids might be the right place? If so, is there some sort of convention I should use for the ID, or is it fairly loosely enforced? I.e. would Sidebar/Accessibility/Label be a good key? I want to make it clear that this is a label for accessibility so someone doesn’t change it without context.

  2. Assuming I’m on the right track, how do I change aria-label="Sidebar" to aria-label="<my internationalized string>"?

  3. As a screen reader user myself, I want these changes in my current wiki. What would be the easiest way to do that? I assume I can build an HTML wiki from the repo pretty easily, and it should be easy to upgrade when these changes land in an official release?

Plugin updates are a bit difficult to manage with a screen reader right now, which is something I’d like to improve with guidance. Drag-and-drop of links is either impossible or so difficult that I don’t know how to do it personally. I know I can find and export/import plugin tiddlers, but the workflow for that isn’t nearly as easy and I haven’t done it in over a year, so I don’t remember how. That’s why I’m focusing on just rebuilding the whole wiki for now, rather than on making them part of a plugin.

Thanks.

1 Like

Hi @nolan welcome to the project. Thanks for your questions, we really appreciate help making TiddlyWiki better for screenreader users. We aim for TiddlyWiki to be universal, which includes the idea of being available to everyone everywhere, with none of the usual barriers like money, or the inability for users to customise industrialised products.

The convention we use at the moment is to describe UI components with two language strings: /Hint for a long description of the component, and /Caption for a short description. We then reuse the caption as the aria label. You can see examples in core tiddlers such as $:/core/ui/Buttons/new-image.

We transclude the language string. For example:

<$button tooltip={{$:/language/Buttons/NewImage/Hint}} aria-label={{$:/language/Buttons/NewImage/Caption}} class=<<tv-config-toolbar-class>> actions={{$:/core/ui/Actions/new-image}}>

Excellent! That’s right: you’d maintain your own fork of TW5, periodically cherry picking commits into PRs to the core.