Merge pull request finos#2778 from finos/update-docs

Update documentation for `3.x`
onesimus-wiafe · Oct 17, 2024 · 788e11c · 788e11c
2 parents 13b26d7 + 8a01cac
commit 788e11c
Show file tree

Hide file tree

Showing 114 changed files with 2,156 additions and 2,639 deletions.
diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md
@@ -1,24 +1,126 @@
 ---
-name: 🐛 Bug Report
-about: If something isn't working as expected 🤔.
-
+name: Bug Report
+about: If something isn't working as expected.
 ---
 
 ## Bug Report
 
 ### Steps to Reproduce:
- 1. ...step 1 description...
- 2. ...step 2 description...
- 3. ...step 3 description...
+
+Please provide a full reproduction of the issue. There are three ways we accept
+repros:
+
+1.  If the issue you are reporting is a UX/UI issue which can be recreated by
+    visiting a Perspective demo _hosted by the project itself_, and any dataset
+    required to reproduce the error can be included in the report. In this case,
+    please provide detailed step-by-step instructions on how to reproduce,
+    including any screenshots which help illustrate, as well as including any
+    fully-encoded test data we may need.
+
+2.  If you are reporting a build or installation issue with the library itself,
+    which can be recreated from a shell. In this case, please provided detailed
+    code blocks describing how you tried to install, which commands were issued,
+    including and dependencies you needed to install and hwo you installed them.
+
+3.  If you are reporting a _anything else_, including but not limited to:
+
+    -   Build issues which require _any_ metadata files e.g. a `package.json`,
+        `Cargo.toml`, etc
+    -   Bundler or packaging errors with JavaScript
+    -   Library functions which return the wrong results or error
+    -   CPU or memory usage performance regressions, or regressions in thread
+        utilization
+
+    In this case, we require a _complete reproduction_ of the issue in the form
+    of a repository. Quoting this exceptional definition from
+    [@Rich-Harris's micro-essay on Repros](https://gist.github.com/Rich-Harris/88c5fc2ac6dc941b22e7996af05d70ff),
+    please follow these guidelines:
+
+    > 1.  Create a sample repo on GitHub (or wherever)
+    > 2.  Demonstrate the problem, and nothing but the problem. If the app where
+    >     you're experiencing the issue happens to use Gulp, I don't care,
+    >     unless the problem involves Gulp. Remove that stuff. Whittle it down
+    >     to the _bare minimum_ of code that reliably demonstrates the issue.
+    >     Get rid of any dependencies that aren't _directly_ related to the
+    >     problem.
+    > 3.  Install all your dependencies to `package.json`. If I can't clone the
+    >     repo and do `npm install && npm run build` (or similar – see point 4)
+    >     to see the problem, because I need some globally installed CLI tool or
+    >     whatever, then you've made it harder to get to the bottom of the
+    >     issue.
+    > 4.  Include instructions in the repo, along with a description of the
+    >     expected and actual behaviour. Obviously the issue should include
+    >     information about the bug as well, but it's really helpful if
+    >     `README.md` includes that information, plus a link back to the issue.
+    >     If there are any instructions beyond `npm install && npm run build`,
+    >     they should go here.
+
+    Some examples which _do not_ qualify as _complete_ and are mostly useless to
+    us for debugging:
+
+    -   Instructions which ask us to visit a website or download an application,
+        even if it is _completely_ open source (and expecially if it is not)
+    -   Instructions which just describe how to create a project, e.g. with a
+        specific build tool or template
+    -   Screenshots of exceptions
+    -   Screenshots of code
+    -   Code snippets copied from a larger application context
 
 ### Expected Result:
-...description of what you expected to see...
+
+Describe what you expected to see. If you are reporting a UX/UI error, this may
+include screenshots with annotations.
 
 ### Actual Result:
-...what actually happened, including full exceptions (please include the entire stack trace, including "caused by" entries), log entries, screen shots etc. where appropriate...
+
+Describe what actually happened, with special attention to the errant behavior.
+Always include:
+
+-   OS and version
+-   Platform/language + version
+
+If you are reporting a UX/UI error:
+
+-   (if websocket) Platform/language + version of remote perspective server.
+-   Full exception/error message if applicable.
+-   Any potentially relevent JavaScript developer console error logs.
+-   Screenshots of the UI in an obviously broken state. (but please try to avoid
+    screenshots of your code, see below)
+
+If you are reporting a library error:
+
+-   (if websocket) Platform/language + version of remote perspective server.
+-   Full exception error capture (please include the entire stack trace,
+    including "caused by" entries), log entries, etc. where appropriate. Please
+    avoid posting screenshots of code (which we may need to debug).
+
+If you are reporting a build or install error:
+
+-   Full error output from running your repro, formatted as a code block (please
+    _do not_ include screenshots of build logs).
 
 ### Environment:
-...version and build of the project, OS and runtime versions, virtualised environment (if any), etc. ...
+
+For JavaScript (browser):
+
+-   `@finos/perspective` version
+-   Browser and version
+-   OS
+-   (if websocket) Language/version/OS of perspective server
+
+For Node.js:
+
+-   `node` version
+-   OS
+
+For Python
+
+-   `python` interpreter version (Only CPython).
+-   package manager and version (conda/pip/\*)
+    -   Are you compiling from an sdist of wheel?
+-   Platform and version (Jupyter/tornado/lib/\*)
+-   OS
 
 ### Additional Context:
-...add any other context about the problem here. If applicable, add screenshots to help explain...
+
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/Feature_request.md b/.github/ISSUE_TEMPLATE/Feature_request.md
@@ -1,17 +1,22 @@
 ---
-name: 🚀 Feature Request
-about: I have a suggestion (and may want to implement it 🙂)!
-
+name: Feature Request
+about: I have a suggestion.
 ---
 
 ## Feature Request
 
 ### Description of Problem:
-...what *problem* are you trying to solve that the project doesn't currently solve?
 
-...please resist the temptation to describe your request in terms of a solution.  Job Story form ("When [triggering condition], I want to [motivation/goal], so I can [outcome].") can help ensure you're expressing a problem statement.
+...what _problem_ are you trying to solve that the project doesn't currently
+solve?
+
+...please resist the temptation to describe your request in terms of a solution.
+Job Story form ("When [triggering condition], I want to [motivation/goal], so I
+can [outcome].") can help ensure you're expressing a problem statement.
 
 ### Potential Solutions:
-...clearly and concisely describe what you want to happen. Add any considered drawbacks.
+
+...clearly and concisely describe what you want to happen. Add any considered
+drawbacks.
 
 ... if you've considered alternatives, clearly and concisely describe those too.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,10 @@
+### Pull Request Checklist
+
+-   [ ] Description which clearly states what problems the PR solves.
+-   [ ] Description contains a link to the Github Issue, and any relevent
+        Discussions, this PR applies to.
+-   [ ] Include new tests that fail without this PR but passes with it.
+-   [ ] Include any relevent Documentation changes related to this change.
+-   [ ] Verify all commits have been _signed_ in accordance with the DCO policy.
+-   [ ] Reviewed PR commit history to remove unnecessary changes.
+-   [ ] Make sure your PR passes _build_, _test_ and _lint_ steps _completely_.
diff --git a/.github/PULL_REQUEST_TEMPLATE/Bugfix.md b/.github/PULL_REQUEST_TEMPLATE/Bugfix.md
diff --git a/.github/PULL_REQUEST_TEMPLATE/Documentation.md b/.github/PULL_REQUEST_TEMPLATE/Documentation.md
diff --git a/.github/PULL_REQUEST_TEMPLATE/Feature.md b/.github/PULL_REQUEST_TEMPLATE/Feature.md
diff --git a/.github/actions/install-deps/action.yaml b/.github/actions/install-deps/action.yaml
@@ -32,6 +32,9 @@ inputs:
     python:
         default: "true"
         description: "Install Python dependencies?"
+    playwright:
+        default: "false"
+        description: "Install browsers for playwright testing"
     clean:
         default: "false"
         description: "Clean unused deps. This is helpful if we run out of HD but slow!"
@@ -48,7 +51,7 @@ runs:
     using: "composite"
     steps:
         - name: Clean System
-          uses: AdityaGarg8/remove-unwanted-software@v3
+          uses: AdityaGarg8/remove-unwanted-software@v4.1
           if: ${{ inputs.clean == 'true' && runner.os != 'Windows' }}
           with:
               remove-android: "true"
@@ -117,13 +120,25 @@ runs:
               vcpkg.exe integrate install
               echo "VCPKG_INSTALLATION_ROOT=${env:VCPKG_INSTALLATION_ROOT}"
               echo "VCPKG_INSTALLATION_ROOT=${env:VCPKG_INSTALLATION_ROOT}" >> $env:GITHUB_OUTPUT
+              echo "${env:VCPKG_INSTALLATION_ROOT}" >> $env:GITHUB_PATH
+              echo "VCPKG_ROOT=${env:VCPKG_INSTALLATION_ROOT}" >> $env:GITHUB_ENV
               dir env:
           env:
               PYTHON_VERSION: ${{ matrix.python-version }}
               VCPKG_DEFAULT_TRIPLET: x64-windows
               VCPKG_PLATFORM_TOOLSET: v143
           if: ${{ runner.os == 'Windows' && inputs.cpp == 'true' }}
 
+        # https://github.com/apache/arrow/issues/38391
+        - if: ${{ runner.os == 'macOS' }}
+          shell: bash
+          run: echo "MACOSX_DEPLOYMENT_TARGET=$(sw_vers -productVersion)" >> $GITHUB_ENV
+
+        # Use python 3.9 from manylinu
+        - run: echo "/opt/python/cp39-cp39/bin" >> $GITHUB_PATH
+          shell: bash
+          if: ${{ runner.os == 'Linux' }}
+
         - name: Set up Python ${{ matrix.python-version }}
           uses: actions/setup-python@v5
           if: ${{ inputs.python == 'true' && runner.os != 'Linux' }}
@@ -179,12 +194,12 @@ runs:
 
         - name: Install JS dependencies
           shell: bash
-          if: ${{ inputs.javascript == 'true' }}
+          if: ${{ inputs.javascript == 'true' && inputs.playwright == 'true' }}
           run: pnpm install
 
         - name: Install JS dependencies
           shell: bash
-          if: ${{ inputs.javascript == 'false' }}
+          if: ${{ inputs.javascript == 'false' || inputs.playwright == 'false'}}
           run: pnpm install --ignore-scripts
 
         - name: Install Python dependencies