Skip to content

Commit

Permalink
* Updated readme and comments to reflect the default-branch name-change.
Browse files Browse the repository at this point in the history
  • Loading branch information
Venryx committed Mar 16, 2024
1 parent 839e4ae commit 9c0ca33
Show file tree
Hide file tree
Showing 6 changed files with 38 additions and 38 deletions.
2 changes: 1 addition & 1 deletion Docs/AccessPolicies.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Overview

To be written. For now, see [the proposal](https://debatemap.app/feedback/proposals/sTggOxurTaGShH97_QGwBg) and [the class](https://github.com/debate-map/app/blob/master/Packages/js-common/Source/DB/accessPolicies/%40AccessPolicy.ts).
To be written. For now, see [the proposal](https://debatemap.app/feedback/proposals/sTggOxurTaGShH97_QGwBg) and [the class](https://github.com/debate-map/app/blob/main/Packages/js-common/Source/DB/accessPolicies/%40AccessPolicy.ts).

Some brief notes:
* The access restrictions do not apply to the server itself, of course; it can access anything for its internal use. However, care should be taken so that that "internal use" doesn't "leak" sensitive information to the caller. (For example, let's say someone searches for all nodes with a given substring in its title, and the server omits an entry due to lacking permissions: if the paging system were to then be "missing" a slot in the first page, this would "leak" that someone made a node with that substring but hid the current user from accessing it [with the creator possibly identifiable based on context]. To resolve this, the server should make sure to not leave "gaps" after entry-removal.)
Expand Down
8 changes: 4 additions & 4 deletions Docs/NodeRevisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
## Overview

There are a few tables involved:
* [nodes](https://github.com/debate-map/app/tree/master/Packages/js-common/Source/DB/nodes/@MapNode.ts): These entries never change; they hold a node's static properties like its type, original creator, etc.
* [nodeRevisions](https://github.com/debate-map/app/tree/master/Packages/js-common/Source/DB/nodeRevisions/@MapNodeRevision.ts): These entries represent the history of "accepted drafts" for a node; the latest entries represents the "current state" of the node's details. (title, tags, etc.)
* [nodeDrafts](https://github.com/debate-map/app/tree/master/Packages/js-common/Source/DB/nodeDrafts/@MapNodeDraft.ts): These entries contain "proposed changes" for a node's details, like changing its title or adding a tag. Generally, these drafts will only change one or two properties at a time, in order to maximize the chance they'll be accepted.
* [nodes](https://github.com/debate-map/app/tree/main/Packages/js-common/Source/DB/nodes/@MapNode.ts): These entries never change; they hold a node's static properties like its type, original creator, etc.
* [nodeRevisions](https://github.com/debate-map/app/tree/main/Packages/js-common/Source/DB/nodeRevisions/@MapNodeRevision.ts): These entries represent the history of "accepted drafts" for a node; the latest entries represents the "current state" of the node's details. (title, tags, etc.)
* [nodeDrafts](https://github.com/debate-map/app/tree/main/Packages/js-common/Source/DB/nodeDrafts/@MapNodeDraft.ts): These entries contain "proposed changes" for a node's details, like changing its title or adding a tag. Generally, these drafts will only change one or two properties at a time, in order to maximize the chance they'll be accepted.

## Acceptance process (planned)

The acceptance process for a draft depends a lot on the [reputation](https://github.com/debate-map/app/tree/master/Docs/UserReputation.md) of the users involved.
The acceptance process for a draft depends a lot on the [reputation](https://github.com/debate-map/app/tree/main/Docs/UserReputation.md) of the users involved.

A draft is accepted (ie. added as the current "official revision") if:
TODO
Expand Down
10 changes: 5 additions & 5 deletions Docs/PackageCodeSyncing.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ In those cases, there still needs to be some way for developers to "coordinate"
### Standard synchronization categories

* The structs/classes/enums representing the information present in the database should all be synced.
* JavaScript path: https://github.com/debate-map/app/tree/master/Packages/js-common/Source/db
* Rust path: https://github.com/debate-map/app/tree/master/Packages/app-server/src/db
* JavaScript path: https://github.com/debate-map/app/tree/main/Packages/js-common/Source/db
* Rust path: https://github.com/debate-map/app/tree/main/Packages/app-server/src/db
* The functions by which RLS (row-level-security) policies are applied should be synced between the postgres and Rust versions.
* SQL/Postgres path: https://github.com/debate-map/app/tree/master/Scripts/InitDB (files: RLSPolicies.sql, RLSHelpers.sql)
* Rust path: https://github.com/debate-map/app/tree/master/Packages/app-server/src/utils/db/rls (files: rls_policies.sql, rls_helpers.sql)
* SQL/Postgres path: https://github.com/debate-map/app/tree/main/Scripts/InitDB (files: RLSPolicies.sql, RLSHelpers.sql)
* Rust path: https://github.com/debate-map/app/tree/main/Packages/app-server/src/utils/db/rls (files: rls_policies.sql, rls_helpers.sql)
* For the logic determining whether a "command" is allowed, the situation is not quite as clear-cut. Basically though:
* For "basic checks" (eg. whether user has general permission for action X on object Y), the logic should be present on both the client and server (generally using a single call to a function like `IsUserCreatorOrMod` -- or soon, to some generic function that performs checks based on the relevant access policy/policies); generally the frontend should "apply" these basic checks at the visibility level, rather than "graying out" the option or the like. (eg. for a node that a non-mod user had no part in creating, they would not expect a "Delete" option to show up at all)
* For "complex checks", whether the logic is replicated on the client depends on whether the action already shows a dialog to the user when clicked.
Expand All @@ -42,4 +42,4 @@ General notes:
* 2\) `function CanUserDeleteNode(user: User, nodeID: string): boolean {...}` Yes, it should have the notation; it is not obvious from the function name and parameters what exact permission logic is required for a node to be deleted.

Specific groups:
* Many of the functions present in the database-related folders (paths to: [js folder](https://github.com/debate-map/app/tree/master/Packages/js-common/Source/db), [rs folder](https://github.com/debate-map/app/tree/master/Packages/app-server/src/db)) are present in both languages.
* Many of the functions present in the database-related folders (paths to: [js folder](https://github.com/debate-map/app/tree/main/Packages/js-common/Source/db), [rs folder](https://github.com/debate-map/app/tree/main/Packages/app-server/src/db)) are present in both languages.
2 changes: 1 addition & 1 deletion Packages/monitor-backend/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Backend code for `monitor.debatemap.app`, which is meant for admin-related funct
* 2\) Don't provide functionality that other pods will want to rely on. (in rare cases where another pod might query `monitor-backend`, it should only be for small/non-essential reasons)
* 3\) It should continue to function regardless of failures in any of the other pods. This means:
* 3.1\) It should have an independent storage system, running "in pod", with its own k8s persistent-volume-claim.
* 3.2\) Its frontend code (see [monitor-client](https://github.com/debate-map/app/tree/master/Packages/monitor-client)) should be served from the same pod; ie. `monitor-backend` is both the web-server and app-server for the `monitor.debatemap.app` endpoint. (having a separate web-server pod isn't helpful here, since the user count is very limited, so the caching/scaling requirements don't differ significantly)
* 3.2\) Its frontend code (see [monitor-client](https://github.com/debate-map/app/tree/main/Packages/monitor-client)) should be served from the same pod; ie. `monitor-backend` is both the web-server and app-server for the `monitor.debatemap.app` endpoint. (having a separate web-server pod isn't helpful here, since the user count is very limited, so the caching/scaling requirements don't differ significantly)
* 3.3\) For accessing "shared functionality" provided by other pods (eg. data from a third-party logging/monitoring tool), such access should always be done in a manner which handles failures gracefully.
* 4\) The storage that `monitor-backend` uses, and the format it uses to communicate with its frontend, should be considered transient (ie. "nukeable").
* 4.1\) That is, no one should rely on these things remaining the same between commits.
Expand Down
2 changes: 1 addition & 1 deletion Packages/monitor-client/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Debate Map (package: monitor-client)

Frontend code for `monitor.debatemap.app`; see [monitor-backend](https://github.com/debate-map/app/tree/master/Packages/monitor-backend) for more info.
Frontend code for `monitor.debatemap.app`; see [monitor-backend](https://github.com/debate-map/app/tree/main/Packages/monitor-backend) for more info.

## Guide modules

Expand Down
52 changes: 26 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,39 +31,39 @@ Development of Debate Map is partially supported by [The Society Library](https:

# Freeform documentation

* [**Quick start**](https://github.com/debate-map/app/tree/master/Docs/QuickStart.md) (new devs should start here)
* [Coding style](https://github.com/debate-map/app/tree/master/Docs/CodingStyle.md)
* [General conventions](https://github.com/debate-map/app/tree/master/Docs/GeneralConventions.md)
* [Authentication](https://github.com/debate-map/app/tree/master/Docs/Authentication.md) (outdated)
* [Access policies](https://github.com/debate-map/app/tree/master/Docs/AccessPolicies.md) (slightly outdated)
* [User reputation](https://github.com/debate-map/app/tree/master/Docs/UserReputation.md) (ideas phase)
* [Node revisions](https://github.com/debate-map/app/tree/master/Docs/NodeRevisions.md) (outdated)
* [Migration notes](https://github.com/debate-map/app/tree/master/Docs/MigrationNotes.md)
* [Package code-syncing](https://github.com/debate-map/app/tree/master/Docs/PackageCodeSyncing.md)
* [Compilation speed](https://github.com/debate-map/app/tree/master/Docs/CompilationSpeed.md)
* [Common issues](https://github.com/debate-map/app/tree/master/Docs/CommonIssues.md)
* [**Quick start**](https://github.com/debate-map/app/tree/main/Docs/QuickStart.md) (new devs should start here)
* [Coding style](https://github.com/debate-map/app/tree/main/Docs/CodingStyle.md)
* [General conventions](https://github.com/debate-map/app/tree/main/Docs/GeneralConventions.md)
* [Authentication](https://github.com/debate-map/app/tree/main/Docs/Authentication.md) (outdated)
* [Access policies](https://github.com/debate-map/app/tree/main/Docs/AccessPolicies.md) (slightly outdated)
* [User reputation](https://github.com/debate-map/app/tree/main/Docs/UserReputation.md) (ideas phase)
* [Node revisions](https://github.com/debate-map/app/tree/main/Docs/NodeRevisions.md) (outdated)
* [Migration notes](https://github.com/debate-map/app/tree/main/Docs/MigrationNotes.md)
* [Package code-syncing](https://github.com/debate-map/app/tree/main/Docs/PackageCodeSyncing.md)
* [Compilation speed](https://github.com/debate-map/app/tree/main/Docs/CompilationSpeed.md)
* [Common issues](https://github.com/debate-map/app/tree/main/Docs/CommonIssues.md)

# Packages

* [client](https://github.com/debate-map/app/tree/master/Packages/client): Frontend code that runs in the browser; connects to the `app-server` pod. (and the `monitor-backend` pod, if the user is an admin) \[TypeScript]
* [web-server](https://github.com/debate-map/app/tree/master/Packages/web-server): Serves the static frontend files for the website -- see "client" package above. \[Rust]
* [app-server](https://github.com/debate-map/app/tree/master/Packages/app-server): Serves database queries and backend commands. \[Rust]
* [monitor-client](https://github.com/debate-map/app/tree/master/Packages/monitor-client): Frontend code for `monitor.debatemap.app`; see `monitor-backend` for more info. \[TypeScript]
* [monitor-backend](https://github.com/debate-map/app/tree/master/Packages/monitor-backend): Backend code for `monitor.debatemap.app`, which is meant for admin-related functionality, and has several unique design goals (see [here](https://github.com/debate-map/app/tree/master/Packages/monitor-backend#design-goals)). \[Rust]
* [js-common](https://github.com/debate-map/app/tree/master/Packages/js-common): Code shared between the various JS packages. \[TypeScript]
* [deploy](https://github.com/debate-map/app/tree/master/Packages/deploy): Miscellaneous scripts and such, used in the deployment process.
* [rust-shared](https://github.com/debate-map/app/tree/master/Packages/rust-shared): Code shared between the various Rust packages. \[Rust]
* [rust-macros](https://github.com/debate-map/app/tree/master/Packages/rust-macros): Procedural macros used by other Rust packages. (proc-macros can't be used from the crate they're defined in) \[Rust]
* [client](https://github.com/debate-map/app/tree/main/Packages/client): Frontend code that runs in the browser; connects to the `app-server` pod. (and the `monitor-backend` pod, if the user is an admin) \[TypeScript]
* [web-server](https://github.com/debate-map/app/tree/main/Packages/web-server): Serves the static frontend files for the website -- see "client" package above. \[Rust]
* [app-server](https://github.com/debate-map/app/tree/main/Packages/app-server): Serves database queries and backend commands. \[Rust]
* [monitor-client](https://github.com/debate-map/app/tree/main/Packages/monitor-client): Frontend code for `monitor.debatemap.app`; see `monitor-backend` for more info. \[TypeScript]
* [monitor-backend](https://github.com/debate-map/app/tree/main/Packages/monitor-backend): Backend code for `monitor.debatemap.app`, which is meant for admin-related functionality, and has several unique design goals (see [here](https://github.com/debate-map/app/tree/main/Packages/monitor-backend#design-goals)). \[Rust]
* [js-common](https://github.com/debate-map/app/tree/main/Packages/js-common): Code shared between the various JS packages. \[TypeScript]
* [deploy](https://github.com/debate-map/app/tree/main/Packages/deploy): Miscellaneous scripts and such, used in the deployment process.
* [rust-shared](https://github.com/debate-map/app/tree/main/Packages/rust-shared): Code shared between the various Rust packages. \[Rust]
* [rust-macros](https://github.com/debate-map/app/tree/main/Packages/rust-macros): Procedural macros used by other Rust packages. (proc-macros can't be used from the crate they're defined in) \[Rust]
<!--
// planned packages
* [graphlink-server](https://github.com/debate-map/app/tree/master/Packages/graphlink-server): Library providing a GraphQL endpoint based on a PostgreSQL database, with support for live-queries. (Rust) [to be split into separate repo]
* [graphlink-server](https://github.com/debate-map/app/tree/main/Packages/graphlink-server): Library providing a GraphQL endpoint based on a PostgreSQL database, with support for live-queries. (Rust) [to be split into separate repo]
-->

# Guide modules

* Note: The section below is for the "active guide modules" that are likely to be used. Ones unlikely to be used are placed in the [ExtraGuideModules.md](https://github.com/debate-map/app/tree/master/Docs/ExtraGuideModules.md) file.
* Note: The section below is for the "active guide modules" that are likely to be used. Ones unlikely to be used are placed in the [ExtraGuideModules.md](https://github.com/debate-map/app/tree/main/Docs/ExtraGuideModules.md) file.
* Tip: You can link someone to a specific guide-module by adding `#MODULE_NAME` to the end of the url. (eg: `https://github.com/debate-map/app#setup-general`)
* Tip: If you want to search the text of collapsed guide-modules, you can either view the [readme's source text](https://github.com/debate-map/app/blob/master/README.md?plain=1), or open the dev-tools "Elements" tab and use its ctrl+f search function.
* Tip: If you want to search the text of collapsed guide-modules, you can either view the [readme's source text](https://github.com/debate-map/app/blob/main/README.md?plain=1), or open the dev-tools "Elements" tab and use its ctrl+f search function.



Expand All @@ -80,10 +80,10 @@ Development of Debate Map is partially supported by [The Society Library](https:
* Note: Installation of a new command-line tool generally requires that you restart your terminal/IDE in order for its binaries to be accessible simply by name (assuming the installer has added its folder to the `Path` environment-variable automatically). So if a step fails due to "Command X is not recognized", check this first. (To save space, this "restart your terminal/IDE before proceeding" note will not be repeated in other guide-modules/steps.)
* 2\) Clone/download this repo to disk. (https://github.com/debate-map/app.git)
* 3\) Install this repo's dependencies by running: `yarn install`
* 4\) There is an ugly additional step that used to be required here, relating to a messy transition in the NPM ecosystem from commonjs to esm modules. For now, this issue is being worked around in this repo through use of [these](https://github.com/debate-map/app/tree/master/patches) and [these](https://github.com/Venryx/web-vcore/tree/master/patches) patch files (which are auto-applied by npm/yarn). However, if you get strange webpack/typescript build errors relating to commonjs/esm modules, it's probably related to [this issue](https://github.com/apollographql/apollo-client/pull/8396#issuecomment-894563662), which may then require another look at the patch files (or attempting to find a more reliable solution).
* 4\) There is an ugly additional step that used to be required here, relating to a messy transition in the NPM ecosystem from commonjs to esm modules. For now, this issue is being worked around in this repo through use of [these](https://github.com/debate-map/app/tree/main/patches) and [these](https://github.com/Venryx/web-vcore/tree/master/patches) patch files (which are auto-applied by npm/yarn). However, if you get strange webpack/typescript build errors relating to commonjs/esm modules, it's probably related to [this issue](https://github.com/apollographql/apollo-client/pull/8396#issuecomment-894563662), which may then require another look at the patch files (or attempting to find a more reliable solution).
* 5\) Copy the `.env.template` file in the repo root, rename the copy to `.env`, and fill in the necessary environment-variables. At the moment, regular frontend and backend devs don't need to make any modifications to the new `.env` file; only backend deployers/maintainers (ie. those pushing changes to the cloud for production) have environment-variables they need to fill in.

> If you're looking for a higher-level "quick start" guide, see here: [Quick start](https://github.com/debate-map/app/tree/master/Docs/QuickStart.md)
> If you're looking for a higher-level "quick start" guide, see here: [Quick start](https://github.com/debate-map/app/tree/main/Docs/QuickStart.md)
</details>

Expand Down Expand Up @@ -153,7 +153,7 @@ Port-assignment scheme: (ie. meaning of each digit in `ABCD`)
* D) variant [0: main, 1: served from webpack, etc.]

> Note: Not all web-accessible k8s services are shown in the list above. Specifically:
> * Mere "subcomponents" of the monitoring service: grafana, prometheus, alertmanager (Reason: They're accessible through the monitor tool's subpages/iframes. See [Domains.ts](https://github.com/debate-map/app/blob/master/Packages/js-common/Source/Utils/General/Domains.ts) or [domains.rs](https://github.com/debate-map/app/blob/master/Packages/rust-shared/src/domains.rs) for more details.)
> * Mere "subcomponents" of the monitoring service: grafana, prometheus, alertmanager (Reason: They're accessible through the monitor tool's subpages/iframes. See [Domains.ts](https://github.com/debate-map/app/blob/main/Packages/js-common/Source/Utils/General/Domains.ts) or [domains.rs](https://github.com/debate-map/app/blob/main/Packages/rust-shared/src/domains.rs) for more details.)
</details>

Expand Down

0 comments on commit 9c0ca33

Please sign in to comment.