From ab8d171aae61b8a7950eccc1a4ecb081d91e3054 Mon Sep 17 00:00:00 2001 From: Shazib Hussain Date: Sat, 18 Nov 2023 18:49:42 +0000 Subject: [PATCH 1/5] Adding some contribution guidelines --- docs-sidebar.js | 3 +++ docs/contributing/project-details/advice.md | 5 +++++ docs/contributing/project-details/electron.md | 10 ++++++++++ docs/contributing/project-details/migrations.md | 11 +++++++++++ 4 files changed, 29 insertions(+) create mode 100644 docs/contributing/project-details/advice.md create mode 100644 docs/contributing/project-details/electron.md create mode 100644 docs/contributing/project-details/migrations.md diff --git a/docs-sidebar.js b/docs-sidebar.js index ce67c14f8..592593271 100644 --- a/docs-sidebar.js +++ b/docs-sidebar.js @@ -56,6 +56,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 000000000..cc715a3ff --- /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/electron.md b/docs/contributing/project-details/electron.md new file mode 100644 index 000000000..49b95e268 --- /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 vis `ipcRenderer` + diff --git a/docs/contributing/project-details/migrations.md b/docs/contributing/project-details/migrations.md new file mode 100644 index 000000000..a007ad133 --- /dev/null +++ b/docs/contributing/project-details/migrations.md @@ -0,0 +1,11 @@ +# 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 may 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` \ No newline at end of file From b4cdbb1f87d8cf9602e326e0679e57e1771b56cd Mon Sep 17 00:00:00 2001 From: Shazib Hussain Date: Sat, 18 Nov 2023 18:54:33 +0000 Subject: [PATCH 2/5] refactored out --- docs/contributing/project-details/architecture.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/contributing/project-details/architecture.md b/docs/contributing/project-details/architecture.md index 299d4c019..2778bf128 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. - From 51e686643f517104cc86051022b3bc18b6a72e6a Mon Sep 17 00:00:00 2001 From: Shazib Hussain Date: Sat, 18 Nov 2023 23:07:09 +0000 Subject: [PATCH 3/5] Typo --- docs/contributing/project-details/electron.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/project-details/electron.md b/docs/contributing/project-details/electron.md index 49b95e268..155542080 100644 --- a/docs/contributing/project-details/electron.md +++ b/docs/contributing/project-details/electron.md @@ -6,5 +6,5 @@ * 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 vis `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` From 5442169f57e2621411aa641c093a370b5a4c7e0c Mon Sep 17 00:00:00 2001 From: Shazib Hussain Date: Fri, 24 Nov 2023 23:50:14 +0000 Subject: [PATCH 4/5] Make advised changes --- docs/contributing/project-details/migrations.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/contributing/project-details/migrations.md b/docs/contributing/project-details/migrations.md index a007ad133..707c87f28 100644 --- a/docs/contributing/project-details/migrations.md +++ b/docs/contributing/project-details/migrations.md @@ -4,8 +4,12 @@ There are some important considerations to make when adding a feature with a db * DB Migrations also require publishing a new API version as the migrations also need to be applied there. -* The AQL Schema file may need to be updated to match any table changes. +* 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` \ No newline at end of file +* 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 unneccessary 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. \ No newline at end of file From 0c19aa9cc46bbc3def7a23adef778c0ab4dae8c0 Mon Sep 17 00:00:00 2001 From: Shazib Hussain Date: Sat, 25 Nov 2023 00:06:22 +0000 Subject: [PATCH 5/5] Update migrations.md --- docs/contributing/project-details/migrations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/project-details/migrations.md b/docs/contributing/project-details/migrations.md index 707c87f28..7b45ff217 100644 --- a/docs/contributing/project-details/migrations.md +++ b/docs/contributing/project-details/migrations.md @@ -10,6 +10,6 @@ There are some important considerations to make when adding a feature with a db * 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 unneccessary risk when we can simply stop using them in code. +* 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. \ No newline at end of file +* 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.