Skip to content

A local-first personal finance app

Adding some contribution guidelines (#277)

Shazib Hussain8a90292f9747
diff --git a/docs-sidebar.js b/docs-sidebar.js
index 6afd9e1b5a..34aed978b1 100644
--- a/docs-sidebar.js
+++ b/docs-sidebar.js
@@ -57,6 +57,9 @@ const sidebars = {
items: [
'contributing/project-details/database',
'contributing/project-details/architecture',
+ 'contributing/project-details/electron',
+ 'contributing/project-details/migrations',
+ 'contributing/project-details/advice',
],
},
'contributing/preview-builds',
diff --git a/docs/contributing/project-details/advice.md b/docs/contributing/project-details/advice.md
new file mode 100644
index 0000000000..cc715a3ff2
--- /dev/null
+++ b/docs/contributing/project-details/advice.md
@@ -0,0 +1,5 @@
+# Important Advice
+
+* Any changes made to the `global.Actual` object must happen inside the respective electron and browser preload scripts. Whilst re-assigning items will work in the browser it is not supported in electron.
+
+* Similarly, and changes made to `global.Actual` should be manually tested on the electron builds as well as the browser.
diff --git a/docs/contributing/project-details/architecture.md b/docs/contributing/project-details/architecture.md
index 299d4c0194..2778bf1281 100644
--- a/docs/contributing/project-details/architecture.md
+++ b/docs/contributing/project-details/architecture.md
@@ -7,10 +7,3 @@ When actual runs, it runs the front-end react based web app, as well as a local
In the web app, this background server runs in a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers), and in the electron app it spins up a [background process](https://nodejs.org/dist/latest-v16.x/docs/api/child_process.html#child_processforkmodulepath-args-options) which communicates over [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API).
The code which is used by this background server, as well as code which is shared across the web app and desktop versions of actual typically lives inside the `loot-core` package.
-
-### Electron Notes
-
-* Generally speaking, it is unlikely that features/fixes you contribute to actual will require electron-specific changes. If you think that is likely feel free to discuss on github or in the actual discord.
-
-* Details of the motivation behind the usage of WebSockets in the electron app can be found in the [Pull Request](https://github.com/actualbudget/actual/pull/1003) where the changes were made.
-
diff --git a/docs/contributing/project-details/electron.md b/docs/contributing/project-details/electron.md
new file mode 100644
index 0000000000..1555420802
--- /dev/null
+++ b/docs/contributing/project-details/electron.md
@@ -0,0 +1,10 @@
+# Electron Notes
+
+* Generally speaking, it is unlikely that features/fixes you contribute to actual will require electron-specific changes. If you think that is likely feel free to discuss on github or in the actual discord.
+
+* Details of the motivation behind the usage of WebSockets in the electron app can be found in the [Pull Request](https://github.com/actualbudget/actual/pull/1003) where the changes were made.
+
+* Due to Electron security requirements there are some restrictions on what can be passed from front-end to (local) back-end. Generally limited to strings/ints via the `ipcRenderer`
+
+* Making changes to the `global.Actual` object MUST happen inside the preload script. Due to electron security requirements this object is siloed and can only pass messages via `ipcRenderer`
+
diff --git a/docs/contributing/project-details/migrations.md b/docs/contributing/project-details/migrations.md
new file mode 100644
index 0000000000..7b45ff2178
--- /dev/null
+++ b/docs/contributing/project-details/migrations.md
@@ -0,0 +1,15 @@
+# DB Migrations Guide
+
+There are some important considerations to make when adding a feature with a db migration.
+
+* DB Migrations also require publishing a new API version as the migrations also need to be applied there.
+
+* The AQL Schema file will likely need to be updated to match any table changes.
+
+* You must place your migration file in the `loot-core/migrations` folder, with a strict naming convention.
+
+* The naming convention is as follows: `TIMESTAMP_name.sql`. for example. `1694438752000_add_goal_targets.sql`
+
+* It is strongly discouraged to try to remove columns and tables, This makes reverting changes impossible and introduces unnecessary risk when we can simply stop using them in code.
+
+* You should be very deliberate with your migration. When adding a feature, try to think about future scenarios and options that may be desired later, so we can minimise the number of migrations.