Skip to content

Latest commit

 

History

History
131 lines (96 loc) · 4.71 KB

CONTRIBUTING.md

File metadata and controls

131 lines (96 loc) · 4.71 KB
Raw

Contributing to jupyter/accessibility

Code of Conduct

This project follows the Jupyter Code of Conduct.

Goal

To facilitate improving the accessibility of interactive computing. We are trying to make this process smoother to:

  • capture the state of an accessibility feature across number of separate Jupyter repositories at different states of development as pull requests
  • deploy them together on Binder to share with people for testing
  • assess them on GitHub Actions to provide reports, raw data, and feedback
  • work as a team to get the pull requests merged
  • show progress towards an accessibility Roadmap

Core Workflow

  1. Get a free GitHub account
  2. Make one (or more) pull requests to one (or more) Jupyter repositories
  3. Make a pull request to jupyter/accessibility:ci that changes repos.toml to include the pull requests from step 2
    • the pull request target should be the ci branch
  4. Construct the appropriate Binder link and paste the Markdown in (all of) the pull request(s)
  5. Gather and discuss findings
  6. Update the upstream pull requests
  7. Repeat steps 3+ as needed
  8. Get upstream pull requests merged

Why is this so complicated?

Improving the accessibility of a Jupyter client may require touching many repositories:

Each component likely has its own developer workflows and culture. In this repository, we've tried to collect the workflows in a declarative, productive way, that allows trying out Code From The Future, without blocking review until every pull request merged.

On Binder

Reproduce locally with doit app docs

To meet some of the above challenges, this repository's interactive state on Binder is composed of a full live development environment made of the (hopefully) harmonious union of different repositories at different states of development from GitHub branches and pull requests.

Implemented in repo2docker's postBuild stage, this allows for creating very specific environments without re-inventing too much.

On GitHub Actions

Reproduce locally with doit report

The GitHub Actions workflow performs many of the same steps as Binder, but also:

  • runs pa11y-ci against all generated content
  • uploads reports as artifacts which are available to any GitHub user

On Your Computer

You can do all the things that happen on Binder and GitHub Actions on your computer.

  • Get Miniforge for conda:

    • if your computer runs Windows, please ensure you:
      • install conda on short path, e.g. c:\mf
      • clone this repo to a short path, e.g. c:\git\a11y

  • Make an environment like the one in Binder

    conda env update .binder/environment.yml
conda activate a11y

  • List all the doit tasks

    doit list --all --status

  • Try out different doit tasks! The most fun one is:

    doit start

    which will start JupyterLab!

Under the Hood

doit

The workhorse of this approach is doit. It is a python-based tool that manages:

  • running tasks
    • in the right order
      • when (parts of) files change

Why Not (make|docker|pants|scons|bazel|grunt|...) instead?

In building and delivering complex environments, we've found doit offers a mix of portability, expressiveness, and productivity. Being Python-based we can be relatively sure it's going to work anywhere Jupyter works. Despite it's quirks, python is good at reading strings and running processes. Ensuring work isn't repeated is really important when welding together n development workflows.

PRs welcome to add alternative workflows that meet all these criteria!