diff --git a/README.md b/README.md index 0116eb01..d1a97133 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ Given this ownership and responsibility, A11ybats will provide guidance and supp [The Component Catalog application can be found here](https://noredink-ui.netlify.app/). ## Component Library Foundations + - Adherence to the component library [accessibility policy](#accessibility-policy) - Adherence to the [NoRedInk UI Style Guide](https://paper.dropbox.com/doc/UI-Style-Guide-and-Caveats-PvOLxeX3oyujYEzdJx5pu) and [Guidelines for Sharing User-Facing Changes with Design](https://paper.dropbox.com/doc/Guidelines-for-Sharing-User-Facing-Changes-with-Design-bdKGQtYH9qO9I00hUkA6k) - Interoperability and consistency of components with each other and with the NoRedInk app @@ -18,12 +19,14 @@ Given this ownership and responsibility, A11ybats will provide guidance and supp - Test coverage and testability of each component and of [the Component Catalog](https://noredink-ui.netlify.app/) ## Accessibility policy + - No new components will be added to the component library if they do not conform to [WCAG 2.1 AA accessibility guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/). Similarly, no existing components will be modified such that the component falls out of conformance with these guidelines. - For new components, UX designers & stakeholders are responsible for making their best faith effort to follow the [Accessibility Guidelines for Product Development](https://paper.dropbox.com/doc/PlcoE22OpOhB6eWCF4rFj?noDesktopRedirect=1) to include accessibility details in their spec and code. A11ybats will help fill in any gaps, but your team is responsible for the first pass. - Existing components that do not conform to [WCAG 2.1 AA accessibility guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) are being updated by A11ybats to be conformant. (We believe we have a comprehensive backlog of updates to make, but feel free to ask us if you think you spot an accessibility issue. 🙏 ) - Components in the NoRedInk app which are NOT in the component library but which are shared or could be shared across multiple interfaces may be added to the component library over time by A11ybats or by any team, ideally with any necessary accessibility improvements, in accordance with the [`noredink-ui` versioning policy](#versioning-policy). # Contribution guidelines + ## What belongs in the component library? 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. @@ -35,8 +38,8 @@ Contributing to the component library is characterized by close consultation wit **🔧 Modifying an existing component** 1. As soon as you have a rough idea of the modification you need (from the product/design perspective), please ping A11ybats in the [#ask-accessibilibats](https://noredink.slack.com/archives/C02NVG4M45U) Slack channel with details about the modification you’re planning to make. - - We may either give you the okay in the Slack thread, or we may request a brief **kickoff sync** to discuss implementation details. You may also request a sync rather than providing details in Slack. - - Once A11ybats give you the go-ahead to begin work… + - We may either give you the okay in the Slack thread, or we may request a brief **kickoff sync** to discuss implementation details. You may also request a sync rather than providing details in Slack. + - Once A11ybats give you the go-ahead to begin work… 2. Review the [PR template](/.github/pull_request_template.md) in advance so that you understand contribution requirements in advance, or go ahead and open a draft PR so you can use the [PR template](/.github/pull_request_template.md) as you work. 3. Feel free to [reach out to A11ybats](https://noredink.slack.com/archives/C02NVG4M45U) with any questions as you work - it might save you headaches or code rewrites later! 4. Request a PR review from your team as usual. There is no need to add A11ybats as a reviewer unless this was mentioned as a requirement in your kickoff sync. @@ -45,21 +48,21 @@ Contributing to the component library is characterized by close consultation wit **🌟 Creating a new component** 1. As soon as you have a rough idea of the new component you need (from the product/design perspective), please ping A11ybats in the [#ask-accessibilibats](https://noredink.slack.com/archives/C02NVG4M45U) Slack channel to request a brief **kickoff sync**. - - A11ybats should be able to sync with you anywhere from immediately following your request to ~48 hours from your request. We want to unblock you asap! - - In the kickoff sync, you can expect to start by sharing your concept with A11ybats. Next, A11ybats will ensure you are aware of our contribution guidelines and will provide high-level guidance about anything important to know before you build your component. For example, in some cases, we may already have existing code that meets your needs or that we prefer you base your new component on. (Hooray! Less work for you!) We may also give you some accessibility pointers. - - If necessary for more complex work, we’ll schedule followup syncs/pairing with you. - - Once A11ybats give you the go-ahead to begin work… + - A11ybats should be able to sync with you anywhere from immediately following your request to ~48 hours from your request. We want to unblock you asap! + - In the kickoff sync, you can expect to start by sharing your concept with A11ybats. Next, A11ybats will ensure you are aware of our contribution guidelines and will provide high-level guidance about anything important to know before you build your component. For example, in some cases, we may already have existing code that meets your needs or that we prefer you base your new component on. (Hooray! Less work for you!) We may also give you some accessibility pointers. + - If necessary for more complex work, we’ll schedule followup syncs/pairing with you. + - Once A11ybats give you the go-ahead to begin work… 2. Feel free to [reach out to A11ybats](https://noredink.slack.com/archives/C02NVG4M45U) with any questions as you work - it might save you headaches or code rewrites later! 3. Review the [PR template](/.github/pull_request_template.md) in advance so that you understand contribution requirements in advance, or go ahead and open a draft PR so you can use the [PR template](/.github/pull_request_template.md) as you work. 4. Before beginning dev work, we strongly recommend working closely with a UX designer to produce a **clear, comprehensive** component spec. Here are some tips for developing a good spec before starting component work: - - UX designers & stakeholders are responsible for making their best faith effort at following the [Accessibility Guidelines for Product Development](https://paper.dropbox.com/doc/PlcoE22OpOhB6eWCF4rFj?noDesktopRedirect=1) to include accessibility details in their spec and code. A11ybats will help fill in any gaps, but your team is responsible for the first pass. - - In the spec, include details about which properties need to be configurable and which configuration options are necessary for each property. For example, if your component allows color configurations, you might want developers to specify any hex code as the color, or you may wish to limit them to a particular subset of [NoRedInk's colors](https://noredink-ui.netlify.app/#/doodad/Colors), etc. + - UX designers & stakeholders are responsible for making their best faith effort at following the [Accessibility Guidelines for Product Development](https://paper.dropbox.com/doc/PlcoE22OpOhB6eWCF4rFj?noDesktopRedirect=1) to include accessibility details in their spec and code. A11ybats will help fill in any gaps, but your team is responsible for the first pass. + - In the spec, include details about which properties need to be configurable and which configuration options are necessary for each property. For example, if your component allows color configurations, you might want developers to specify any hex code as the color, or you may wish to limit them to a particular subset of [NoRedInk's colors](https://noredink-ui.netlify.app/#/doodad/Colors), etc. 5. If you'd like to have multiple small PRs as you build out the functionality of the component, we recommend branching the small PRs off an omnibus-style component-specific branch instead of branching each small PR off of master. 6. For your initial PR, please request a PR review from your team as usual, but also add A11ybats as an additional PR reviewer. - - A11ybats will review your PR solely for the purposes of ensuring that your new component adheres to the [Component Library Foundations](#component-library-foundations). We may point out bugs if we happen to find them, but that’s not what we’ll be looking for — **your team is ultimately responsible for testing/coordinating testing of your new component**. - - For minor iterations on your new component, there’s no need to request A11ybat PR review again. We’ll keep an eye on smaller changes as you make them. If you aren’t sure if your changes are big enough for another A11ybat PR review, just ask! + - A11ybats will review your PR solely for the purposes of ensuring that your new component adheres to the [Component Library Foundations](#component-library-foundations). We may point out bugs if we happen to find them, but that’s not what we’ll be looking for — **your team is ultimately responsible for testing/coordinating testing of your new component**. + - For minor iterations on your new component, there’s no need to request A11ybat PR review again. We’ll keep an eye on smaller changes as you make them. If you aren’t sure if your changes are big enough for another A11ybat PR review, just ask! 7. Once your component is in a state that’s ready for production, please request an accessibility review from A11ybats by dropping a note in [#ask-accessibilibats](https://noredink.slack.com/archives/C02NVG4M45U). Our turnaround time should be relatively quick, but in the meantime… -8. Start creating a [QA Flightplan](https://paper.dropbox.com/doc/QA-landing-page-FAQ--BNKlATfTHdgnJa48lcR5NrVSAg-wLYVa0lEmkaiJB09CXHRn) as if this were a new feature. We recommend requesting that the QA team *at least* tests your new component within the Component Catalog netlify branch preview. (You can always request additional QA of your component as implemented in the NoRedInk app later.) Simple components may have a simple flightplan, and that’s okay! +8. Start creating a [QA Flightplan](https://paper.dropbox.com/doc/QA-landing-page-FAQ--BNKlATfTHdgnJa48lcR5NrVSAg-wLYVa0lEmkaiJB09CXHRn) as if this were a new feature. We recommend requesting that the QA team _at least_ tests your new component within the Component Catalog netlify branch preview. (You can always request additional QA of your component as implemented in the NoRedInk app later.) Simple components may have a simple flightplan, and that’s okay! 9. Once A11ybats have completed their accessibility review, make updates to your QA Flightplan if needed and submit your QA Flightplan to QA according to [QA’s processes](https://paper.dropbox.com/doc/QA-landing-page-FAQ--BNKlATfTHdgnJa48lcR5NrVSAg-wLYVa0lEmkaiJB09CXHRn). 10. When you're ready to publish your component, please refer to [the noredink-ui versioning policy](#versioning-policy), which includes guidance on permitted API changes per release. 11. A11ybats keep an eye on all noredink-ui updates and may request modifications to your work if it does not adhere to the [Component Library Foundations](#component-library-foundations). @@ -67,6 +70,7 @@ Contributing to the component library is characterized by close consultation wit # Developing, deploying, & versioning ## Getting Started + 1. Setup your [development environment](#developing-with-nix) 2. Run some [tests](#tests) 3. Check out [some examples](https://noredink-ui.netlify.app/) @@ -91,12 +95,12 @@ It is automatically loaded in the Nix environment. Here are some things you might need to do: -| Task | Command | -|------|---------| +| 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` | +| Update Nixpkgs | `niv update nixpkgs` | +| See all our dependencies | Look in `shell.nix` | +| See all our sources | `niv show` | ## Developing with Buck @@ -106,6 +110,7 @@ The instructions above will work until they're removed from the repo, but if you ## Tests Run tests with + - `shake test` - `elm-test` @@ -154,10 +159,8 @@ Any NoRedInk engineer can deploy a new version of `noredink-ui`. Generally, we p - Because of branch protection you will not be able to push a tag like: `git push origin master 22.x.y` (The previous command requires permissions to push directly to master even if you have no changes). - Instead, please push your new `22.x.y` tag with the following: `git push origin 22.x.y` - Once you've published, you should see the latest version at . It can take a few minutes to show up. - ### Troubleshooting a release If you get something like this: @@ -211,20 +214,21 @@ We should change this process if we feel it's not working for us! ## Moving Widgets to `noredink-ui` If you are moving in a widget from the monolith: + - Copy the contents of `Nri.SomeModule` and its tests to `Nri.Ui.SomeModule.V1` in `noredink-ui` - Publish! - If you feel confident upgrading pre-existing usages of the widget, switch over to it everywhere! - If the new version introduces big changes and you'd rather keep the old one around for now, rename `Nri.SomeModule` to `Nri.DEPRECATEDSomeModule` in the monolith and start using `Nri.Ui.SomeModule.V1` where you need it - ## Phasing out old versions Our 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: - - We should avoid introducing new references to old versions of a widget - - When touching code that uses a widget, prefer upgrading to the latest version - - If you introduce a new version of a widget, please consider taking the time to upgrade all previous usages - - If for some reason this isn't feasible, create a story in your team's backlog so that you can prioritize it separately without disrupting your current work - - You can delete an old version of a widget when there are no usages left - - Note: this will be a major version bump, so you may want to batch deletions together + +- We should avoid introducing new references to old versions of a widget +- When touching code that uses a widget, prefer upgrading to the latest version +- If you introduce a new version of a widget, please consider taking the time to upgrade all previous usages + - If for some reason this isn't feasible, create a story in your team's backlog so that you can prioritize it separately without disrupting your current work +- You can delete an old version of a widget when there are no usages left + - Note: this will be a major version bump, so you may want to batch deletions together