Merge remote-tracking branch 'origin/master' into sso-exclusive-all

Author: haraldschilly

DEVELOPMENT.md

@@ -28,12 +28,6 @@ The name was coined in fall 2016 and changed around spring 2017.
 
 ## Contributors
 
-### YOU?!
-
-New -- Feb 2022:  If you want to work on something at https://github.com/sagemathinc/cocalc/issues, [contact us](email:[email protected]), and we might be able to pay you!
-
-### Contributors
-
 - Greg Bard
 - Rob Beezer
 - Blaec Bejarano
@@ -52,7 +46,7 @@ New -- Feb 2022:  If you want to work on something at https://github.com/sagemat
 - Jonathan Thompson
 - Todd Zimmerman
 
-... and _many_ others: See https://github.com/sagemathinc/cocalc/graphs/contributors
+... and others: See https://github.com/sagemathinc/cocalc/graphs/contributors
 
 ## Copyright/License
 
@@ -92,3 +86,4 @@ We are grateful to BrowserStack for providing infrastructure to test CoCalc.
 ### Google
 
 We thank Google for donating over \$150K in cloud credits since 2014 to support this project.
+

README.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/Issue Triage.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/README.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.
+