update the docs

Author: williamstein

docs/Issue Triage.md

@@ -1,32 +1,34 @@
 ## Issue Triage
+
 Contributors with sufficient permissions on the CoCalc repo can help by adding
 labels to triage issues:
 
-* Yellow, **A**-prefixed labels state which **area** of CoCalc the issue relates to.   
+- Yellow, **A**-prefixed labels state which **area** of CoCalc the issue relates to.  
   Answers the question: "Where should I be looking?"
 
-* Green, **E**-prefixed labels explain the type of **experience** necessary
+- Green, **E**-prefixed labels explain the type of **experience** necessary
   to fix the issue.  
   Answers the question "What kind of effort is necessary?"
 
-* Red, **I**-prefixed labels indicate the **importance** (relevance) of the issue.  
+- Red, **I**-prefixed labels indicate the **importance** (relevance) of the issue.  
   Answers the question: "Why is this important?"
 
-* **M** is market segment priority. 
+- Orange, **P**-prefixed labels indicate a bug's **priority**.
 
-* Orange, **P**-prefixed labels indicate a bug's **priority**.
+- **M** is market segment priority. (ws: these are confusing and should be merged with the P- priorities)
 
-* The purple **meta** label denotes a list of issues collected from other categories.
+- The purple **meta** label denotes a list of issues collected from other categories.
 
-* The black, **blocked** label denotes an issue blocked by another.
+- The black, **blocked** label denotes an issue blocked by another.
 
-* Finally, **upstream** signals the problem is related to a library, usually includes a link to another issue.
+- Finally, **upstream** signals the problem is related to a library, usually includes a link to another issue.
 
 If you're looking for somewhere to start, check out the [E-easy][eeasy] tag.
 
-[eeasy]:https://github.com/sagemathinc/cocalc/labels/E-easy
+[eeasy]: https://github.com/sagemathinc/cocalc/labels/E-easy
 
 ### List of labels and their descriptions
+
 Most tags should be self explanatory but some can be unclear. If you're unsure what a label means how it's different from another email John Jeng at [email protected]. He'll probably add it to the description here.
 
 - `blocked` -- Always link what the issue is blocked by.
@@ -37,5 +39,4 @@ Most tags should be self explanatory but some can be unclear. If you're unsure w
 - `I-software request` -- Requests for adding something to be installed in CoCalc by default.
 - `I-UA` -- Text that needs to be reworded or a tip that needs to get written.
 
-
 Inspired by [Rust's triage system](https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage).

docs/README.md

@@ -1,29 +1,5 @@
 # Guidelines
-This collection of files provides general knowledge for working with the CoCalc.
-
-**WARNING (June 2021): we haven't looked at this in years, and it is probably all wrong.**
-
-Ask clarifying questions and update this as you go.
-
-# Webapp Code Layout
-`entry-point.coffee`
-- `desktop_app.cjsx` / `mobile_app.cjsx`
- - Projects View (`projects.cjsx`)
- - Account View (`account.cjsx`)
- - Project View (`project_page.cjsx`)
- - About View (`r_help.cjsx`)
 
-Additionally, it has top level widget components:
-- Help
-- File Notifications (`file_use.cjsx`)
-- Connection Status
-
-
-# External Resources
-HTML/CSS
-- [Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/)
+This collection of files provides general knowledge for working with the CoCalc.
 
-Redux:
-- [Getting Started](https://egghead.io/courses/getting-started-with-redux)
-- [Idiomatic Redux](https://egghead.io/courses/building-react-applications-with-idiomatic-redux)
-- [Why you might not need redux](https://medium.com/@dan_abramov/you-might-not-need-redux-be46360cf367#.g6zxcajc5)
+Last Updated: September 2024.

docs/Random Notes.md

@@ -0,0 +1,82 @@
+# CoCalc Style Guide
+
+## Language (Javascript/Typescript/Python)
+
+- Prettier: Use the _defaults_ with the latest version of prettier on all of our Javascript and Typescript code. Use yapf for Python.
+
+  - NOTE: prettier's defaults change over time, but we don't ever just run it on our full massive codebase.
+
+- Typescript: Always prefer Typescript over Javascript and CoffeeScript
+
+  - NOTE: there's still some coffeescript code in CoCalc; it's terrifying and should all be rewritten in Typescript.
+
+- Variable Names: Use the standard Javascript camelCase convention for variable names, unless there is a good reason otherwise. Good reasons include: variable names that are also used in PostgreSQL and interop with Python (lower case with underscores).
+
+  - NOTE: there's a lot of Javascript code in cocalc that uses Python conventions. Long ago Nicholas R. argued "by using Python conventions we can easily distinguish our code from other code"; in retrospect, this was a bad argument, and only serves to make Javascript devs less comfortable in our codebase, and make our code look weird compared to most Javascript code. Rewrite it.
+
+- Javascript Methods: Prefer arrow functions for methods of classes.
+
+  - it's standard
+  - avoids subtle problems involving "this" binding
+  - easier to search for function definition in editor
+  - NOTE: there's a lot of code in cocalc that uses non-arrow-functions; rewrite it and don't add more of this.
+
+- Async Programming: Prefer async/await to callbacks if at all possible.
+
+  - NOTE: CoCalc used to not use async/await or promises at all, so there is still some code that uses the callback [async library](https://github.com/caolan/async). This code is terrifying, and it should all be rewritten.
+
+## React
+
+- Functional Components and hooks: Always prefer functional components with hooks over class components
+
+  - NOTE: there are still a lot of class components in cocalc; rewrite them.
+
+- Use the style of https://react.dev/learn/typescript for React with Typescript:
+  - typescript detects unused props,
+  - defaults are natural and do not need MyButton.defaultProps, which is deprecated,
+  - uses minimal notation (less characters typed),
+  - very common in tutorials and other code
+  - NOTE: a lot of our code used to be class components, hence still is written like `prop.[propname]`
+
+In particular, use
+
+```ts
+function MyButton({ title, disabled }: MyButtonProps) {
+  return <button disabled={disabled}>{title}</button>;
+}
+```
+
+and do NOT use
+
+```ts
+function MyButton(props: MyButtonProps) {
+  return <button disabled={props.disabled}>{props.title}</button>;
+}
+```
+
+or
+
+```ts
+const MyButton: React.FC<MyButtonProps> = (props) => {
+  return <button disabled={props.disabled}>{props.title}</button>;
+};
+```
+
+- Memoization: avoid using `React.memo`
+
+  - it leads to subtle bugs
+  - it's far better to render 20 items slowly, e.g., using virtualization, then to render 20000 items quickly
+  - NOTE: there's 100\+ uses of React.memo in cocalc right now; I'm not happy with this, though I wrote them. It's almost always a bad idea.
+
+## UI Design
+
+- As much as possible, use [Antd components](https://ant.design/) in the standard way.
+
+  - Avoid doing new design if possible; use the conventions and components of Antd.
+  - If there is a cancel button next to another button, then cancel goes first, following the Antd convention, e.g., see Popconfirm.
+  - NOTE: We wrote a lot of custom components, e.g., for number input, before switching fully to Antd, and those are still partly in use. Rewrite all of that to use Antd.
+
+- Bootstrap:
+  - CoCalc used to use jquery + bootstrap (way before react even existed!) for everything, and that's still in use for some things today (e.g., Sage Worksheets). Rewrite or delete all this.
+  - CoCalc also used to use react-bootstrap, and sadly still does. Get rid of this.
+

docs/STYLE.md

@@ -1,146 +1,58 @@
 # Editors and Widgets
 
 ## Editor
-A file editor uses `register` from `project_file.coffee`.
+
+A file editor uses `register`.
 A family of file editors is the set of editors which use the same store.
-Each family of editors has its own folder inside `smc-webapp/`.
-Inside this folder is typically the following
-- main.cjsx
-- register.coffee
-- actions.coffee
-- store.coffee
-- README.md
-
-Additional supporting files are also common:
-- info.coffee
-- styles.coffee
-- util.coffee
+Each family of editors has its own folder inside `packages/frontend/`.
 
 Treat these folders somewhat like modules.
-Typically you will only be importing from `main.cjsx` and `register.coffee`.
-
-## Widget
-Widgets stand alone and do not call `register`.
-See "smc-webapp/widget-markdown-input/" for an example.
 
 ## Actions, Tables, Stores, Oh My!
+
 We use
 CQRS = command query responsibility segregation.
 
-It means that you have two different things you communicate with (e.g., "Actions" and "Store"). One is used only for commands (=actions). The other is used only to get out data (=store). Segregation means they are completely separate. It's the design pattern we're using.
+It means that you have two different things you communicate with \(e.g., "Actions" and "Store"\). One is used only for commands \(=actions\). The other is used only to get out data \(=store\). Segregation means they are separate. It's the design pattern we're using.
 
 If something doesn't fit into that at all, and you don't want to change the store or UI to reflect that, then that something should be somewhere else -- not in actions or store.
-CQRS = command query responsibility segregation.
 
 ### Stores
+
 - Store functions should always be pure functions
 
-Computed values are
- - Only get called when a component is rendered which depends on the function
- - Callable from outside React code
- - Not stored in the redux state. Maintain redux state as pure data
-
-```ts
-{redux, computed, depends, rtypes} = require('app-state-framework')
-redux.createStore
-    name: 'account'
-
-    # state types without a defined selector default to
-    # @get('key_name') from the store
-    # Prefer to write store.get('key_name') to be explict
-    stateTypes :
-        time       : rtypes.string
-        user_type  : rtypes.string
-        first_name : rtypes.string
-        last_name  : rtypes.string
-        full_name  : computed rtypes.string
-        greetings  : computed rtypes.string
-
-    # Define the dependencies of computed values
-    full_name: depends('first_name', 'last_name') ->
-        return "#{@first_name} + #{@last_name}"
-
-    # Computed values may call other computed values
-    greeting: depends('full_name', 'time') ->
-        return "Hello #{@full_name} good #{get_english_time_period_name(@time)}"
-
-# Define private functions outside of the store declaration
-get_english_time_period_name: (time_of_day) ->
-    # ... some computation
-
-```
-Importing them in a high level component:
-```coffee
-ProjectPage = rclass
-    reduxProps:
-        account :
-            full_name : rtypes.string
-            greeting  : rtypes.string
-
-```
-Importing values from outside stores
-```coffee
-redux.createStore
-    name: "project_store"
-
-    # Declares what values to import from other stores
-    # These are not available using reduxProps but are
-    # available as dependencies for computed values
-    reduxState:
-        account :
-            full_name : rtypes.string
-
-    stateTypes:
-        shown_greeting : computed rtypes.string
-
-    shown_greeting: depends('full_name') ->
-        return "Hello, " + @full_name
-```
-Run time store definitions can be created as follows:
-```coffee
-create_project_store_def = (name, project_id) ->
-    name: name
-
-    project_id: project_id
-```
+Computed values are used in a few places. They were a bad idea and all code that uses them should be rewritten. React hooks solve the same problem in a much better way.
 
 ### Actions
-Actions are called to make state changes.
-They do not directly manipulate the UI.
 
+Actions are called to make state changes. They do not directly manipulate the UI.
 
 ## Q and A
 
-* [hsy]> How to change a value in a store? What patterns are preferred?
-
-* [hsy]> What are the steps to make a react component actually "react" to changes in a given store?
-  * preparation step:
-  * setup step:
-  * details to take care of? (e.g. control exactly when to re-render)
 
 The following questions are specific for projects, but are meant to be general:
 
-* not project related, maybe callback, maybe return value, doesn't change store → misc
+- not project related, maybe callback, maybe return value, doesn't change store → misc
 
-It depends.  misc is pure javascript and generally just stuff that could be used on both the frontend and backend and doesn't have anything to do with sage_client communication.  It's utility functions.
+It depends. misc is pure javascript and generally just stuff that could be used on both the frontend and backend and doesn't have anything to do with sage_client communication. It's utility functions.
 
-* project related, maybe callback, no return value, doesn't change store → store ? (e.g. `ensure_directory_exists` ?)
+- project related, maybe callback, no return value, doesn't change store → store ? (e.g. `ensure_directory_exists` ?)
 
-No.  The methods of the store should all be "pure" functions of the immutable js state.  There should be no callbacks ever, and nothing that should have any impact on any state anywhere.    The store is a container of state and the interface is "ways to get at that state".   (Exception: there is a method called "wait", which calls a callback when a certain condition on the store holds.)
+No. The methods of the store should all be "pure" functions of the immutable js state. There should be no callbacks ever, and nothing that should have any impact on any state anywhere. The store is a container of state and the interface is "ways to get at that state". (Exception: there is a method called "wait", which calls a callback when a certain condition on the store holds.)
 
-* project related, maybe callback, has return value, doesn't change store → somewhere else ?
+- project related, maybe callback, has return value, doesn't change store → somewhere else ?
 
-Somewhere else, e.g,. a module scope function or class or function in client.coffee.   We want to minimize these as much as possible, as they are harder to reason about, but obviously sometimes they are necessary.    Example: synctables involve tons of such methods.
+Somewhere else, e.g,. a module scope function or class or function in client.coffee. We want to minimize these as much as possible, as they are harder to reason about, but obviously sometimes they are necessary. Example: synctables involve tons of such methods.
 
-* project related, no callback, no return value, changes store → action
+- project related, no callback, no return value, changes store → action
 
-Yes, that's the ideal case.    These can of course be asynchronous functions -- e.g., copying a file -- but rather than expressing what happens as it progresses via callback(s), the instead update the store as the run.   Then the UI can display what happens (or not).
+Yes, that's the ideal case. These can of course be asynchronous functions -- e.g., copying a file -- but rather than expressing what happens as it progresses via callback(s), the instead update the store as the run. Then the UI can display what happens (or not).
 
-* project related, has callback, no return value, maybe changes store → action, but only for "internal" methods
+- project related, has callback, no return value, maybe changes store → action, but only for "internal" methods
 
 Yes, to write clean code the non-public api for Actions can have all kinds of such "traditional" methods.
 
-* project related, no callback, has return value, changes store → shouldn't exist at all
+- project related, no callback, has return value, changes store → shouldn't exist at all
 
 Yes, exactly.