Merge remote-tracking branch 'origin/master' into delete-project-data

Author: haraldschilly

.gitignore

@@ -154,5 +154,5 @@ venv
 
 # frontend/i18n files, which are created during build or updating the languages
 src/packages/frontend/i18n/extracted.json
-src/packages/frontend/i18n/*.compiled.json
+src/packages/frontend/i18n/trans/*.compiled.json
 

DEVELOPMENT.md

@@ -6,6 +6,25 @@ CoCalc is web-based software that enables collaboration in research, teaching, a
 
 **CoCalc** supports sophisticated calculations that arise in teaching, research, and authoring documents. This includes working with the full data science and scientific Python stack, [SageMath](https://www.sagemath.org), [Julia](https://julialang.org), [R Statistics](https://cocalc.com/doc/r-statistical-software.html), [Octave](https://www.gnu.org/software/octave/), and much more. It also offers capabilities to author documents in [LaTeX](https://cocalc.com/doc/latex-editor.html), R/knitr and Markdown, storing and organizing files, a web-based [Linux Terminal](https://doc.cocalc.com/terminal.html), an [X11 graphical desktop](https://doc.cocalc.com/x11.html), and communication tools like a [chatrooms](https://doc.cocalc.com/chat.html), [course management](https://cocalc.com/doc/teaching.html) and more.  It is the best choice for [teaching remote scientific courses](https://cocalc.com/doc/teaching.html).
 
+## Quick Start
+
+1. Visit https://cocalc.com
+2. Sign up for a free account
+3. Create a new project
+4. Choose a computational environment (e.g., Jupyter Notebook, Sage Worksheet, LaTeX Editor)
+5. Start collaborating with others in real-time
+
+## Key Features
+
+- **Jupyter Notebooks**: Interactive Python, R, and Julia environments
+- **Sage Worksheets**: Powerful mathematical computations
+- **LaTeX Editor**: Collaborative document creation with real-time preview
+- **Linux Terminal**: Full command-line access
+- **Computational Whiteboard**: Visual collaboration and code execution
+- **Course Management**: Tools for teaching and managing classes
+- **Real-time Collaboration**: Work together seamlessly on projects
+- **Version Control**: Built-in time travel and project history
+
 ## Website
 
 - [CoCalc](https://cocalc.com/index.html) -- commercial CoCalc hosting and support
@@ -20,6 +39,24 @@ CoCalc is web-based software that enables collaboration in research, teaching, a
 You can obtain a packaged version of CoCalc for your own on-premises infrastructure: [**CoCalc Cloud**](https://doc-cloud.cocalc.com/).
 It runs on Kubernetes and inherits the security and scalability of the SaaS platform.
 
+### CoCalc Cloud
+
+CoCalc Cloud runs on Kubernetes and inherits the security and scalability of the SaaS platform. To get started:
+
+1. Visit https://cocalc.com/pricing/onprem for pricing information
+2. Contact [email protected] to discuss deployment options
+3. Prepare your Kubernetes cluster
+4. Follow the deployment guide at https://doc-cloud.cocalc.com/
+5. Configure your instance and start using your self-hosted CoCalc
+
+### CoCalc-Docker (for smaller deployments or personal use)
+
+1. Ensure Docker is installed on your system
+2. Visit the CoCalc-Docker repository: https://github.com/sagemathinc/cocalc-docker
+3. Follow the installation and usage instructions provided in the repository's README
+
+For more detailed information on self-hosting options, please contact [email protected].
+
 ## History
 
 _CoCalc_ was formerly called _SageMathCloud_.
@@ -28,11 +65,7 @@ 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
+CoCalc is made possible by the hard work of many contributors. Our team includes mathematicians, computer scientists, and software engineers from around the world. Key contributors include:
 
 - Greg Bard
 - Rob Beezer
@@ -52,7 +85,9 @@ 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
+
+We welcome new contributions! If you're interested in contributing, please see our Contributing Guidelines (link to be added).
 
 ## Copyright/License
 
@@ -82,6 +117,14 @@ In particular, [CoCalc OnPrem](https://cocalc.com/pricing/onprem) is designed fo
 
 The scripts [here](https://github.com/sagemathinc/cocalc/tree/master/src/dev) might be helpful.  We do most of our development of CoCalc on https://cocalc.com itself.  CoCalc requires pnpm version at least 9.
 
+## Support and Community
+
+- **User Manual**: https://doc.cocalc.com/
+- **Mailing List**: https://groups.google.com/forum/#!forum/cocalc
+- **Discord Chat**: https://discord.gg/nEHs2GK
+- **Bug Reports**: https://github.com/sagemathinc/cocalc/issues
+- **Commercial Support**: https://cocalc.com/pricing
+
 ## Acknowledgements
 
 ### Browserstack

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.
+