docs: add docs related to contributing

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to Numberscope
+
+## If you are new to software development and like written guides...
+
+Read our [onboarding doc](./doc/onboarding.md).
+
+## If you are new to software development and like videos...
+
+Watch the video series on contributing to Numberscope
+[here](https://www.youtube.com/playlist?list=PLA4KIQBQQRb5ccOdr9v0iLw_fKHup1PkU).
+This video series will introduce you to Numberscope, GitHub, the software we
+use in the Numberscope project, and the workflow for contributing to
+Numberscope.
+
+## If you are experienced, follow these steps...
+
+(This assumes you're working on the numberscope/frontscope repository, but it
+applies to other repos as well.)
+
+1. [Create a fork of the numberscope/frontscope repo](./doc/working-with-git-and-github.md#create-a-fork).
+2. [Clone your fork of numberscope/frontscope](./doc/working-with-git-and-github.md#clone-a-repo).
+3. [Create a branch for your contribution](./doc/working-with-git-and-github.md#create-a-branch).
+4. [Read about basic Git operations](./doc/working-with-git-and-github.md#basic-git-operations).
+5. [Push your branch to GitHub](./doc/working-with-git-and-github.md#push-a-branch).
+6. [Read Numberscope's coding principles guide](./doc/code-principles.md).
+7. [Read Numberscope's style guide](./doc/code-style.md).
+8. [Work through Numberscope's pull request checklist](./doc/pull-request-checklist.md).
+9. [Submit a pull request](./doc/working-with-git-and-github.md#submit-a-pull-request).
+
+## If you need help with Git and contributing...
+
+If you have a Git setup that isn't what Numberscope requires (i.e. do your
+work in your own fork on a feature branch) check out our doc on
+[Gitting it right](./doc/gitting-it-right.md).
+
+## A note on code organization
+
+The Numberscope system actually comprises two code repositories. This
+documentation is generated from the one called `frontscope`
+([GitHub](https://github.com/numberscope/frontscope)), and is primarily
+concerned with the operation and development of that portion of the system.
+
+The code in this `frontscope` repository is responsible for defining and
+displaying the visualizers, and for establishing how to specify the sequences
+the visualizers act on. In general, it provides Numberscope's user interface.
+
+If you need to deal with the code responsible for retrieving integer sequences
+from the [Online Encyclopedia of Integer Sequences (OEIS)](https://oeis.org/),
+or for performing the computations involved in generating sequence entries and
+their factorizations, see `backscope`
+([GitHub](https://github.com/numberscope/backscope)).
+
+## Submit a pull request
+
+(This assumes you're working on the numberscope/frontscope repository, but it
+applies to other repos as well.)
+
+If you've read the
+[Numberscope code principles guide](./doc/code-principles.md) and the
+[Numberscope code style guide](./doc/code-style.md), and you think your code
+is ready to be reviewed by someone at Numberscope, follow these steps:
+
+1. Work through
+   [Numberscope's pull request checklist](./doc/pull-request-checklist.md).
+2. Sync your fork with the main numberscope/frontscope repository. The easiest
+   way to do this is to navigate to the page of your fork of
+   numberscope/frontscope and click "Sync fork" (see the picture below).
+   ![A screenshot of the Sync fork option](./doc/img/sync-fork.png) Another
+   way to do this is to
+   [add numberscope/frontscope as a remote](#add-a-remote) and
+   [sync your fork with the remote original](#sync-local-fork-with-remote-original).
+3. Navigate to the numberscope/frontscope repository. If your fork is synced
+   up with the main numberscope/frontscope repository correctly, you should
+   see a button (see the image below) that says "Compare & pull request".
+   ![A screenshot of the Compare & pull request
+button](./doc/img/compare-and-pull-request.png)
+   Click that button, write up some notes for your pull request, and click the
+   "Create pull request button".

README.md

@@ -34,7 +34,7 @@ explore sequences with Numberscope.
     sequence? Numberscope is designed to make it easy to add new visualizers,
     and this guide will show you how.
 
--   [Contributing](doc/contributing.md)
+-   [Contributing](./CONTRIBUTING.md)
 
     More extensive information about all aspects of Numberscope's code, and
     how you can have your work become part of the project.

doc/code-principles.md

@@ -0,0 +1,30 @@
+# Code principles
+
+There are two acronyms that can help you write better code.
+
+## DRY (Don't Repeat Yourself)
+
+Practically speaking, this means:
+
+-   create function or use a loop instead of copying and pasting blocks of
+    code
+-   use a variable instead of typing the same value multiple times
+-   use your libraries instead of writing something from scratch
+-   use pre-existing solutions instead of writing something from scratch
+-   use a loop or index into an array instead of writing long conditional
+    (`if`/`elif`/`else`) blocks or switch statements
+
+## KISS (Keep It Short (and) Simple)
+
+Practically speaking this means:
+
+-   name your functions so that we know what they do
+-   name your variables so that we know what they are
+-   write your functions so that they only have one responsibility
+-   write your functions so that they don't have too many side effects
+-   write short functions (you should be able to read the function without
+    having to scroll your screen)
+-   write comments that help the reader understand your code instead of
+    comments that merely repeat what the code already says
+-   only have code that actually does something -- don't include any commented
+    out code or code that can't be reached or run

doc/code-style.md

@@ -0,0 +1,13 @@
+# Code style
+
+Outside of the code formatting that is covered by our automated tools (ESLint
+and Prettier as of this writing), we also like to:
+
+# Minimize the number of return statements in a function
+
+-   If you can easily figure out that you need to bail out of a function, go
+    ahead and put a return at the top of the function and then proceed with
+    the rest of the function.
+-   Otherwise, try to minimize the number of return statements in a function.
+    Having them strewn throughout a function (especially a long function) is
+    generally hard to read.

doc/extending.md

@@ -22,4 +22,4 @@ of the options.
 The details of these two main steps are on the following pages. If your
 visualizer ends up working well and you'd like to submit it back to the
 Numberscope project for possible inclusion on the public server, that's one of
-the topics in the [Contributing](contributing.md) section.
+the topics in the [Contributing](../CONTRIBUTING.md) section.

doc/gitting-it-right.md

@@ -0,0 +1,88 @@
+# Gitting it right
+
+If you find yourself with a Git setup that isn't what Numberscope requires
+(i.e. do your work in your own fork on a feature branch), you might be able to
+use this guide to fix your setup.
+
+Here are the different scenarios you could find yourself in and what to do
+about them.
+
+-   1: You have a clone of a Numberscope repository.
+    -   1.A: You haven't made changes.
+        -   [Create a fork](./working-with-git-and-github.md#create-a-fork).
+        -   [Clone your fork](./working-with-git-and-github.md#clone-a-repo).
+        -   [Create a branch](./working-with-git-and-github.md#create-a-branch).
+        -   [Push a branch](./working-with-git-and-github.md#push-a-branch).
+        -   Now you are working in your own fork on a dedicated feature
+            branch, congrats! Read about about basic Git operations below and
+            get to work making a cool visualizer!
+        -   [Read about basic Git operations](./working-with-git-and-github.md#basic-git-operations).
+    -   1.B: You have made changes.
+        -   1.B.1: You are working on the main branch.
+            -   1.B.1.A: You made commits.
+                -   Ask someone at Numberscope for help
+            -   1.B.1.B: You haven't made commits.
+            -   [Stash your changes](./working-with-git-and-github.md#stash-your-changes).
+            -   [Create a branch](./working-with-git-and-github.md#create-a-branch).
+            -   [Create a fork](./working-with-git-and-github.md#create-a-fork).
+            -   [Add the remote of your fork](./working-with-git-and-github.md#add-a-remote).
+            -   [Push the branch to your fork](./working-with-git-and-github.md#push-a-branch).
+            -   [Clone your fork](./working-with-git-and-github.md#clone-a-repo).
+            -   Now you are working in your own fork on a dedicated feature
+                branch, congrats! Read about about basic Git operations below
+                and get to work making a cool visualizer!
+            -   [Read about basic Git operations](./working-with-git-and-github.md#basic-git-operations).
+        -   1.B.2: You are working on a different branch.
+            -   1.B.2.A: You have made commits.
+                -   [Create a fork](./working-with-git-and-github.md#create-a-fork).
+                -   [Add the remote of your fork](./working-with-git-and-github.md#add-a-remote).
+                -   [Push the branch to your fork](./working-with-git-and-github.md#push-a-branch).
+                -   [Clone your fork](./working-with-git-and-github.md#clone-a-repo).
+                -   Now you are working in your own fork on a dedicated
+                    feature branch, congrats! Read about about basic Git
+                    operations below and get to work making a cool visualizer!
+                -   [Read about basic Git operations](./working-with-git-and-github.md#basic-git-operations).
+            -   1.B.2.B: You haven't made commits.
+                -   [Commit your changes](./working-with-git-and-github.md#commit-changes).
+                -   [Create a fork](./working-with-git-and-github.md#create-a-fork).
+                -   [Add the remote of your fork](./working-with-git-and-github.md#add-a-remote).
+                -   [Push the branch to your fork](./working-with-git-and-github.md#push-a-branch).
+                -   [Clone your fork](./working-with-git-and-github.md#clone-a-repo).
+                -   Now you are working in your own fork on a dedicated
+                    feature branch, congrats! Read about about basic Git
+                    operations below and get to work making a cool visualizer!
+                -   [Read about basic Git operations](./working-with-git-and-github.md#basic-git-operations).
+-   2: You have a fork of a Numberscope repository.
+    -   2.A: You haven't made changes.
+        -   [Clone your fork](./working-with-git-and-github.md#clone-a-repo)
+            (if you don't have it on your computer yet).
+        -   [Create a branch](./working-with-git-and-github.md#create-a-branch).
+        -   [Push a branch](./working-with-git-and-github.md#push-a-branch).
+        -   Now you are working in your own fork on a dedicated feature
+            branch, congrats! Read about about basic Git operations below and
+            get to work making a cool visualizer!
+        -   [Read about basic Git operations](./working-with-git-and-github.md#basic-git-operations).
+    -   2.B: You have made changes.
+        -   2.B.1: You are working on the main branch.
+            -   2.B.1.A: You made commits.
+                -   Ask someone at Numberscope for help.
+            -   2.B.1.B: You haven't made commits.
+                -   [Stash your changes](./working-with-git-and-github.md#stash-your-changes).
+                -   [Create a branch](./working-with-git-and-github.md#create-a-branch).
+                -   [Unstash your changes](./working-with-git-and-github.md#unstash-your-changes).
+                -   [Push a branch](./working-with-git-and-github.md#push-a-branch).
+                -   Now you are working in your own fork on a dedicated
+                    feature branch, congrats! Read about about basic Git
+                    operations below and get to work making a cool visualizer!
+                -   [Read about basic Git operations](./working-with-git-and-github.md#basic-git-operations).
+        -   2.B.2: You are working on a different branch.
+            -   2.B.2.A: You have made commits.
+            -   This is the correct setup! Congrats. Feel free to
+                [read about basic Git operations](./working-with-git-and-github.md#basic-git-operations).
+            -   Keep working in this fashion.
+            -   2.B.2.B: You haven't made commits.
+                -   [Commit your changes](./working-with-git-and-github.md#commit-changes).
+                -   Now you are working in your own fork on a dedicated
+                    feature branch, congrats! Read about about basic Git
+                    operations below and get to work making a cool visualizer!
+                -   [Read about basic Git operations](./working-with-git-and-github.md#basic-git-operations).

doc/onboarding.md

@@ -1,4 +1,7 @@
-# Numberscope onboarding
+# Onboarding
+
+This doc was originally meant for students, but it can also be used by
+contributors.
 
 ## A note on commands
 
@@ -55,7 +58,7 @@ Boulder Experimental Mathematics Lab.)
    code. I like to put a directory called `Code` in my home directory. You can
    call this whatever you want.
 7. If you plan to submit new code to become part of Numberscope at some time
-   in the future, it is best to "fork" (make your own copy of) the repository:
+   in the future, _you must_ "fork" (make your own copy of) the repository:
     - Go to https://github.com/numberscope/frontscope.
     - Click the "Fork" button (in the upper right as of this writing) and then
       follow the instructions GitHub provides. You need to create the fork on
@@ -87,9 +90,11 @@ Boulder Experimental Mathematics Lab.)
     ```
     This should print a link that you can open in the browser. Open it and see
     if Numberscope seems to be working.
-10. Finally, before you start changing code, please read the
-    [doc on submitting pull requests](./submitting-pull-requests.md) (it
-    outlines how to submit your code changes).
+10. If you plan on contributing code to Numberscope, _you must_ work in your
+    fork on a dedicated feature branch. To learn how to create a branch, see
+    [this doc](./working-with-git-and-github.md#create-a-branch).
+11. Finally, before you start changing code, please read
+    [our docs on submitting a pull request](../CONTRIBUTING.md#submit-a-pull-request).
 
 See [the doc on running from source](./running-from-source.md) for more
 information.

doc/pull-request-checklist.md

@@ -0,0 +1,30 @@
+# Pull request checklist
+
+## For PR submitters
+
+The PR submitter should:
+
+-   Write or supplement test(s) for the file(s) you touch in your PR.
+-   Make sure Numberscope runs properly, including former supposedly
+    unmodified behaviors and newly implemented ones. In particular, run it via
+    'npm run dev' and with the browser console open and make sure there are no
+    log messages from Numberscope code, warnings, or errors.
+-   Read over the reviewer checklist and try to make sure in advance that your
+    code is going to proceed as smoothly through the review as possible.
+
+## For PR reviewers
+
+-   All new or changed features are appropriately documented.
+-   Tests are appropriately modified for all new or changed features.
+-   The PR is passing lint by running `npm run lint`. There should be no
+    changed files and no warnings/errors.
+-   The PR builds by running `npm run build`. (This also checks type
+    correctness.) There should be no errors, and for now the only allowed
+    warning is the one about some assets being too big.
+-   The PR passes all tests. Right now (Oct. 2022), just by running
+    `npm run test:unit`.
+-   Numberscope runs properly -- basically the same check as on the submitter
+    list, but be sure to exercise as many randomly selected behaviors as you
+    have time for, definitely including but not limited to the ones nominally
+    affected by the PR. This should be done in `npm run preview` mode after a
+    successful build.