NoRedInk’s accessibility team, the Accessibilibats, own the noredink-ui package and the Component Catalog app showcasing its components.
While others may contribute to noredink-ui and are encouraged to do so, the Accessibilibats (a.k.a. A11ybats) are responsible for oversight of the foundational aspects of the component library, a.k.a. “**Component Library Foundations**.”
Given this ownership and responsibility, A11ybats will provide guidance and support to developers and designers who are building new components or working with existing components.
The Component Catalog application can be found here.
noredink-ui versioning policy.Assume anything that seems like it should be a shared component should probably be a shared component. The remaining contribution guidelines will help you make this determination.
Contributing to the component library is characterized by close consultation with A11ybats, who will make every effort to be available as needed. All contributions require at least a quick check-in with A11ybats, ideally before you begin work and at minimum before you merge any PRs. To that end, A11ybats request that you follow the relevant process outlined below to ensure a streamlined workflow for everyone involved:
🔧 Modifying an existing component
🌟 Creating a new component
You can develop this package without installing anything globally by using Nix. To get started, install nix from nixos.org/nix.
After that's set up in your shell (just follow the instructions at the end of the installation script) you can run nix-shell to get a development environment with everything you need.
If you find that inconvenient, try using direnv.
Once that's set up, echo use nix > .envrc and then direnv allow.
Anytime you enter the project your shell will automatically pick up the right dependencies.
If you find that direnv loads too slow, there are faster loading strategies than the default in their wiki.
We use niv to manage Nix dependencies.
It is automatically loaded in the Nix environment.
Here are some things you might need to do:
| Task | Command |
|---|---|
| Add a non-npm, non-Elm dependency packaged with Nix | Look if it's in nixpkgs, or niv add github.com/user/repo |
| Update Nixpkgs | niv update nixpkgs |
| See all our dependencies | Look in shell.nix |
| See all our sources | niv show |
We are in the process of transitioning our build processes to Buck 2.
The instructions above will work until they're removed from the repo, but if you'd like to try the new thing, run script/buck2 build //... or script/buck2 test //....
If you get a failure due to formatting in Buck, you can correct it with buck2 run //:diff_to_comment -- --fix //the-target-that-ci-complained-about.
Run tests with
shake testelm-testYou can run the Puppeteer tests for only one component by passing the name of the component to the test script, for example: ./script/puppeteer-tests-no-percy.sh Button
Travis will run shake ci to verify everything looks good.
You can run this locally to catch errors before you push!
This repo contains an app showcasing all of these UI widgets.
To see them locally:
script/develop.shAnd go to http://localhost:8000/
If you'd like to test your widget in the monolith before publishing, run script/test-elm-package.py ../path_to_this_repo from the monolith's directory.
Any NoRedInk engineer can deploy a new version of noredink-ui. Generally, we prefer to do a release after every change, rather than trying to batch changes together. This is mostly to make QA more straightforward -- especially for the cases where we make a mistake!
elm diff and verify that the changes are not major (versioning policy) and are what you expect. Copy the diff (you'll paste it into a PR description later.)elm bumpelm.json filegit checkout mastergit pullelm publish and follow its promptsgit tag -a 22.x.y -m "Description of this release version: i.e.: 'high-contrast mode highlight style change'"git push origin master 22.x.y (The previous command requires permissions to push directly to master even if you have no changes).22.x.y tag with the following: git push origin 22.x.yOnce you've published, you should see the latest version at https://package.elm-lang.org/packages/NoRedInk/noredink-ui/. It can take a few minutes to show up.
If you get something like this:
-- PROBLEM LOADING DOCS --------------------------------------------------------
I need the docs for 12.17.0 to compute the next version number, so I fetched:
https://package.elm-lang.org/packages/NoRedInk/noredink-ui/12.17.0/docs.json
I got the data back, but it was not what I was expecting. The response body
contains 195076 bytes. Here is the beginning:
[{"name":"Nri.Ui","comment":" A collection of helpers for working with No...
Does this error keep showing up? Maybe there is something weird with your
internet connection. We have gotten reports that schools, businesses, airports,
etc. sometimes intercept requests and add things to the body or change its
contents entirely. Could that be the problem?Then run it with 0.19.0 explicitly (0.19.1 has some problems with big docs):
npx -p [email protected] elm bumpWe try to avoid breaking changes and the associated major version bumps in this package. The reason for that is to avoid the following scenario:
|
x 4.6.0: Adding RadioButton widget
|
x 5.0.0: Breaking change in the TextArea widget
|
x 5.0.1: Styling fix in the Checkbox widget
|Suppose you just released version 5.0.1, a small styling fix in the checkbox widget, for a story you're working on. If the project you're working in currently pulls in noredink-ui at version 4.x, then getting to your styling fix means pulling in a new major version of noredink-ui. This breaks all TextArea widgets across the project, so those will need to be fixed before you can do anything else, potentially a big effort.
To prevent these big Yaks from suddenly showing up in seemingly trivial tasks we prefer to avoid breaking changes in the package. Instead when we need to make a breaking change in a widget, we create a new module for it Nri.Ui.MyWidget.VX. Similarly, when we build custom elements in JavaScript we create a file lib/MyWidget/VX.js and define a custom element nri-mywidget-vX.
That said, we may prune unused modules occasionally.
We should change this process if we feel it's not working for us!
noredink-uiIf you are moving in a widget from the monolith:
Nri.SomeModule and its tests to Nri.Ui.SomeModule.V1 in noredink-uiNri.SomeModule to Nri.DEPRECATEDSomeModule in the monolith and start using Nri.Ui.SomeModule.V1 where you need itOur goal is to gradually move to the newest version of each widget, and remove the old versions when they are no longer used.
This means: