From 200dccb648e3965dbcc588119c583301fc5f9695 Mon Sep 17 00:00:00 2001 From: Lane Sawyer Date: Fri, 13 Sep 2024 10:16:22 -0700 Subject: [PATCH 1/5] chore: Documentation updates and TODOs --- README.md | 16 ++++++++++------ docs/examples.md | 4 ++-- docs/packages.md | 9 +++++++++ docs/todos.md | 28 ++++++++++++++++++++++++++++ 4 files changed, 49 insertions(+), 8 deletions(-) create mode 100644 docs/packages.md create mode 100644 docs/todos.md diff --git a/README.md b/README.md index a9a0ba7..44537ba 100644 --- a/README.md +++ b/README.md @@ -3,20 +3,24 @@ This repository contains a collection of packages for building scalable visualization tools at the Allen Institute. It houses the `vis-[package name]` packages on the Allen Institute GitHub organization's NPM package registry. # Available Packages +TODO: Update this based on the package setup we decide to use - `vis-geometry`: A collection of vector functions for 2D and 3D geometry - `scatterbrain`: A collection of useful utitilites used to build our big-data, scalable, scatterplot tool "Scatterbrain" in the Brain Knowledge Platform # Examples -See the `apps` directory for example projects using the packages. Over time, these examples will become simpler as the base tooling becomes more mature. +See the `example` directory for example projects using the packages. Over time, these examples will become simpler as the base tooling becomes more mature. -For details on running or adding new examples, see the `docs/examples.md` file. - -# Contributing - -Contributions are welcome! We're currently breaking apart the Scattebrain component into smaller, more manageable packages. If you have a package that you think would be useful to others, please open a PR. +For details on running or adding new examples, see the `docs/examples.md` file.s # Using the Libraries See the `docs/using-packages.md` file for information on how to use the packages in your own projects. + +# Contributing + +Contributions are welcome! We're currently breaking apart the Scatterbrain component into smaller, more manageable packages. If you have a package that you think would be useful to others, please open a PR. + +## Getting Started +TODO: Add technology needed for running the project locally for development diff --git a/docs/examples.md b/docs/examples.md index af18733..0445576 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,7 +1,7 @@ # Examples -Examples are located in the `apps` directory. +Examples are located in the `examples` directory. There is a single project that runs all the examples. ## Adding New Examples -To add a new example, create a new directory in the `apps` directory, copy the `package.json` from another example, and then start building! +To add a new example, add new code that demonstrates the feature you want to show off. Then add instructions on using it or UI to activate it on the `examples` application. diff --git a/docs/packages.md b/docs/packages.md new file mode 100644 index 0000000..6060f2c --- /dev/null +++ b/docs/packages.md @@ -0,0 +1,9 @@ +# Packages + +This repository holds multiple published packages. The current list of packages is below: + +- `@alleninstitute/vis-geometry` - Utils for geometric operations +- `@alleninstitute/vis-core` - Scatterbrain stuff, but all this is sorta just core utils. Maybe rename to vis-core? +- `@alleninstitute/vis-react` - React components wrapping up the visualizations defined in `vis-core` + +To install and use these packages, see the instructions in [using-packages.md](./using-packages.md). diff --git a/docs/todos.md b/docs/todos.md new file mode 100644 index 0000000..a297d37 --- /dev/null +++ b/docs/todos.md @@ -0,0 +1,28 @@ +# TODOs + +This document contains a list of tasks that need to be performed in order to prepare the repository for being open-sourced. + +## General +- [ ] Decide if we're using the BSD-3 license or the Allen Institute license and update LICENSE.md accordingly +- [ ] Decide on the name of the packages. Are we sticking with `@alleninstitute/vis-*` or are we going to use a different naming convention, like `@alleninstitute/visualization-toolkit-*`? +- [ ] Decide what packages to have. See `packages.md` for a potential initial list +- [ ] Review existing documentation and make sure it matches the current state of things +- [ ] Add a CONTRIBUTING.md file +- [ ] Add a CODE_OF_CONDUCT.md file + +## Process +- [ ] Set up the CI/CD pipeline +- [ ] Set up changelog generation +- [ ] Set up release automation +- [ ] Configure GitHub settings to protect `main`, require approvals from maintainers before merging, only allow "squash and merge" commits, add templates for issues, PR templates, etc. + +## Tooling +- [ ] Choose and set up a linter +- [ ] Decide if we want to stick with Prettier for formatting +- [ ] Fix `only-allow` making `npm ci` fail occasionally on consuming libraries or remove it entirely +- [ ] (Optional) Benchmarking tooling to measure and track performance + +## Refactor +- [ ] Clean up public API functions to be nicer to use (config object vs long list of arguments, rename as needed, etc.) +- [ ] Move code to proper packages once that's decided (see `packages.md`) +- [ ] Install newly refactored code in `bkp-client` to ensure it's working and nice to use From 7b8088cf372e341fa05c28d8f8b8a1c5236493ff Mon Sep 17 00:00:00 2001 From: Lane Sawyer Date: Thu, 26 Sep 2024 16:28:46 -0700 Subject: [PATCH 2/5] Update todos.md --- docs/todos.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/todos.md b/docs/todos.md index a297d37..ea98dde 100644 --- a/docs/todos.md +++ b/docs/todos.md @@ -3,7 +3,7 @@ This document contains a list of tasks that need to be performed in order to prepare the repository for being open-sourced. ## General -- [ ] Decide if we're using the BSD-3 license or the Allen Institute license and update LICENSE.md accordingly +- [x] Decide if we're using the BSD-3 license or the Allen Institute license and update LICENSE.md accordingly: BSD-3 was selected - [ ] Decide on the name of the packages. Are we sticking with `@alleninstitute/vis-*` or are we going to use a different naming convention, like `@alleninstitute/visualization-toolkit-*`? - [ ] Decide what packages to have. See `packages.md` for a potential initial list - [ ] Review existing documentation and make sure it matches the current state of things From 56394001bd67e293849a3e7ffed5390f113d37fb Mon Sep 17 00:00:00 2001 From: Lane Sawyer Date: Thu, 21 Nov 2024 14:25:36 -0800 Subject: [PATCH 3/5] PR feedback from Skyler --- README.md | 16 ++++++++-------- docs/examples.md | 2 +- docs/packages.md | 12 +++++++++--- docs/todos.md | 28 ---------------------------- 4 files changed, 18 insertions(+), 40 deletions(-) delete mode 100644 docs/todos.md diff --git a/README.md b/README.md index 736406c..0649f44 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,13 @@ This repository contains a collection of packages for building scalable visualization tools at the Allen Institute. It houses the `vis-[package name]` packages on the Allen Institute GitHub organization's NPM package registry. # Available Packages + TODO: Update this based on the package setup we decide to use +- `vis-dzi`: A renderer for [Deep Zoom Images](https://en.wikipedia.org/wiki/Deep_Zoom) - `vis-geometry`: A collection of vector functions for 2D and 3D geometry -- `scatterbrain`: A collection of useful utitilites used to build our big-data, scalable, scatterplot tool "Scatterbrain" in the Brain Knowledge Platform +- `vis-omezarr`: A renderer for [OME-Zarr](https://ngff.openmicroscopy.org/latest/) datasets +- `vis-scatterbrain`: A collection of useful utilities used to build our big-data, scalable, scatterplot tool "Scatterbrain" in the Brain Knowledge Platform (will be renamed to `vis-core` in the future) # Examples @@ -14,6 +17,10 @@ See the `example` directory for example projects using the packages. Over time, For details on running or adding new examples, see the `docs/examples.md` file. +# Contributing + +Contributions are welcome! We're currently breaking apart the Scatterbrain component into smaller, more manageable packages. If you have a package that you think would be useful to others, please open a PR. + # Installation for Development This project uses [Node.js](https://nodejs.org) and [pnpm](https://pnpm.io/). We use [Volta](https://volta.sh/) to manage the versions of each. If you're not using Volta, check the "volta" key in the root `package.json` for the Node and pnpm versions we're using when developing. @@ -23,10 +30,3 @@ Volta has experimental support for pnpm, so [follow the steps on their docs](htt # Using the Libraries See the `docs/using-packages.md` file for information on how to use the packages in your own projects. - -# Contributing - -Contributions are welcome! We're currently breaking apart the Scatterbrain component into smaller, more manageable packages. If you have a package that you think would be useful to others, please open a PR. - -## Getting Started -TODO: Add technology needed for running the project locally for development diff --git a/docs/examples.md b/docs/examples.md index 0445576..40fe753 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,6 +1,6 @@ # Examples -Examples are located in the `examples` directory. There is a single project that runs all the examples. +Examples are located in the `examples` directory. There is a single command that runs all the examples on one website: `npm run dev` ## Adding New Examples diff --git a/docs/packages.md b/docs/packages.md index 6060f2c..18f1935 100644 --- a/docs/packages.md +++ b/docs/packages.md @@ -2,8 +2,14 @@ This repository holds multiple published packages. The current list of packages is below: -- `@alleninstitute/vis-geometry` - Utils for geometric operations -- `@alleninstitute/vis-core` - Scatterbrain stuff, but all this is sorta just core utils. Maybe rename to vis-core? -- `@alleninstitute/vis-react` - React components wrapping up the visualizations defined in `vis-core` +- `vis-dzi`: A renderer for [Deep Zoom Images](https://en.wikipedia.org/wiki/Deep_Zoom) +- `vis-geometry`: A collection of vector functions for 2D and 3D geometry +- `vis-omezarr`: A renderer for [OME-Zarr](https://ngff.openmicroscopy.org/latest/) datasets +- `vis-scatterbrain`: A collection of useful utilities used to build our big-data, scalable, scatterplot tool "Scatterbrain" in the Brain Knowledge Platform (will be renamed to `vis-core` in the future) To install and use these packages, see the instructions in [using-packages.md](./using-packages.md). + +## Future Packages + +- `@alleninstitute/vis-core` - The core utilities common across all visualizations. This package will be the foundation for all other packages. +- `@alleninstitute/vis-react` - React component implementations of each of the visualization packages. diff --git a/docs/todos.md b/docs/todos.md deleted file mode 100644 index ea98dde..0000000 --- a/docs/todos.md +++ /dev/null @@ -1,28 +0,0 @@ -# TODOs - -This document contains a list of tasks that need to be performed in order to prepare the repository for being open-sourced. - -## General -- [x] Decide if we're using the BSD-3 license or the Allen Institute license and update LICENSE.md accordingly: BSD-3 was selected -- [ ] Decide on the name of the packages. Are we sticking with `@alleninstitute/vis-*` or are we going to use a different naming convention, like `@alleninstitute/visualization-toolkit-*`? -- [ ] Decide what packages to have. See `packages.md` for a potential initial list -- [ ] Review existing documentation and make sure it matches the current state of things -- [ ] Add a CONTRIBUTING.md file -- [ ] Add a CODE_OF_CONDUCT.md file - -## Process -- [ ] Set up the CI/CD pipeline -- [ ] Set up changelog generation -- [ ] Set up release automation -- [ ] Configure GitHub settings to protect `main`, require approvals from maintainers before merging, only allow "squash and merge" commits, add templates for issues, PR templates, etc. - -## Tooling -- [ ] Choose and set up a linter -- [ ] Decide if we want to stick with Prettier for formatting -- [ ] Fix `only-allow` making `npm ci` fail occasionally on consuming libraries or remove it entirely -- [ ] (Optional) Benchmarking tooling to measure and track performance - -## Refactor -- [ ] Clean up public API functions to be nicer to use (config object vs long list of arguments, rename as needed, etc.) -- [ ] Move code to proper packages once that's decided (see `packages.md`) -- [ ] Install newly refactored code in `bkp-client` to ensure it's working and nice to use From dc14de62f290680ce778f22805f3542232982f03 Mon Sep 17 00:00:00 2001 From: Lane Sawyer Date: Thu, 21 Nov 2024 14:26:56 -0800 Subject: [PATCH 4/5] Deleted a sentence on accident --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 0649f44..f0e0236 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ For details on running or adding new examples, see the `docs/examples.md` file. Contributions are welcome! We're currently breaking apart the Scatterbrain component into smaller, more manageable packages. If you have a package that you think would be useful to others, please open a PR. +See the CONTRIBUTING.md file for more information on how to contribute to the project! + # Installation for Development This project uses [Node.js](https://nodejs.org) and [pnpm](https://pnpm.io/). We use [Volta](https://volta.sh/) to manage the versions of each. If you're not using Volta, check the "volta" key in the root `package.json` for the Node and pnpm versions we're using when developing. From 2ab8e93851baa8b3757cf0b178115aeb5b8eb950 Mon Sep 17 00:00:00 2001 From: Lane Sawyer Date: Thu, 21 Nov 2024 14:32:19 -0800 Subject: [PATCH 5/5] Final fixes for README --- README.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f0e0236..179e5d6 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,42 @@ -# Allen Institute Vis +# Allen Institute Visualization TypeScript Libraries -This repository contains a collection of packages for building scalable visualization tools at the Allen Institute. It houses the `vis-[package name]` packages on the Allen Institute GitHub organization's NPM package registry. +This repository contains a collection of TypeScript libraries to help software engineers building scalable visualization tools at the Allen Institute. It houses the `vis-[package name]` packages on the Allen Institute GitHub organization's NPM package registry. -# Available Packages +**The published packages are in alpha or beta states. They may fundamentally change as we continue building out functionality.** They are used in a production environment so they are relatively stable, but the APIs are not yet finalized. -TODO: Update this based on the package setup we decide to use +## Available Packages + +The following is the list of packages and their descriptions: - `vis-dzi`: A renderer for [Deep Zoom Images](https://en.wikipedia.org/wiki/Deep_Zoom) - `vis-geometry`: A collection of vector functions for 2D and 3D geometry - `vis-omezarr`: A renderer for [OME-Zarr](https://ngff.openmicroscopy.org/latest/) datasets - `vis-scatterbrain`: A collection of useful utilities used to build our big-data, scalable, scatterplot tool "Scatterbrain" in the Brain Knowledge Platform (will be renamed to `vis-core` in the future) -# Examples +We use [Semantic Versioning](https://semver.org/) for our packages. As of November 2024, all of them are in the `0.0.x` range, indicating that they are in early development. + +## Level Of Support + +We are planning on occasional updating this tool with no fixed schedule. Community involvement is encouraged through both issues and pull requests. + +## Examples -See the `example` directory for example projects using the packages. Over time, these examples will become simpler as the base tooling becomes more mature. +See the `examples` directory for example projects using the packages. Over time, these examples will become more fully featured as the base tooling becomes more mature. For details on running or adding new examples, see the `docs/examples.md` file. -# Contributing +## Contributing Contributions are welcome! We're currently breaking apart the Scatterbrain component into smaller, more manageable packages. If you have a package that you think would be useful to others, please open a PR. See the CONTRIBUTING.md file for more information on how to contribute to the project! -# Installation for Development +## Installation for Development This project uses [Node.js](https://nodejs.org) and [pnpm](https://pnpm.io/). We use [Volta](https://volta.sh/) to manage the versions of each. If you're not using Volta, check the "volta" key in the root `package.json` for the Node and pnpm versions we're using when developing. Volta has experimental support for pnpm, so [follow the steps on their docs](https://docs.volta.sh/advanced/pnpm) to get it enabled. -# Using the Libraries +## Using the Libraries See the `docs/using-packages.md` file for information on how to use the packages in your own projects.