From 27db2c4a28004ca50300d74b94bb39ba1f3d60a7 Mon Sep 17 00:00:00 2001 From: sethkfman Date: Mon, 6 Nov 2023 13:53:25 -0700 Subject: [PATCH 1/7] fixed the secure coding doc path --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c8d5a6f..680f7d4 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,6 @@ This is a living repository — nothing is set in stone! If you're member of Met - [Guide to Pull Requests](./docs/pull-requests.md) - [JavaScript Guidelines](./docs/javascript.md) - [Secure Development Lifecycle Policy](./docs/sdlc.md) -- [Secure Coding Guidelines](./docs/docs/secure-coding-guidelines.md) +- [Secure Coding Guidelines](./docs/secure-coding-guidelines.md) - [TypeScript Guidelines](./docs/typescript.md) - [Unit Testing Guidelines](./docs/unit-testing.md) From fa49cfc3026ae3788646b552fd9eede44c0b3dd6 Mon Sep 17 00:00:00 2001 From: sethkfman Date: Fri, 19 Jan 2024 10:59:03 -0700 Subject: [PATCH 2/7] added first draft of mirgrations best practice --- docs/mirgrations.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/mirgrations.md diff --git a/docs/mirgrations.md b/docs/mirgrations.md new file mode 100644 index 0000000..3d30053 --- /dev/null +++ b/docs/mirgrations.md @@ -0,0 +1,10 @@ +# State Migration Best Practices + +These best practices should apply to any team that contributes to an application that leverages local state. + +## Best Practices +- When to Add a Migration: You should add a migration whenever you make a change to the shape of your state that is not backwards-compatible. This includes adding or removing properties, changing the type of a property, or moving properties around within the state tree (e.g. breaking controllers changes, etc...). +- Detecting Errors in a Migration: The best way to detect errors in a migration is through thorough testing. Write tests that take various shapes of old state and ensure that they are correctly transformed into the new state shape. Also, use TypeScript or another type system to help catch type errors. +- Handling Migration Errors: If a migration fails, you should have a strategy in place to handle the error. This could be as simple as logging the error and continuing with the default state, or it could involve more complex error recovery logic. In any case, it's important to ensure that your app can still function in some way even if a migration fails. +- Keeping Migrations Idempotent: Make sure your migrations are idempotent, meaning they can be run multiple times without changing the result beyond the initial application. This makes migrations safer and easier to test. +- Removing Old Migrations: Over time, you may accumulate many migrations. At some point, it may be safe to remove old migrations, especially if you know that all users have migrated to a newer version of the state. Be cautious with this, as removing a migration could break the ability to upgrade for any users who are still on old versions of the state. From 6c5a51df6a32817ed8fa921cd8ef92f787f3f4fb Mon Sep 17 00:00:00 2001 From: sethkfman Date: Fri, 19 Jan 2024 11:01:09 -0700 Subject: [PATCH 3/7] added coding example --- docs/mirgrations.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/mirgrations.md b/docs/mirgrations.md index 3d30053..1447501 100644 --- a/docs/mirgrations.md +++ b/docs/mirgrations.md @@ -6,5 +6,28 @@ These best practices should apply to any team that contributes to an application - When to Add a Migration: You should add a migration whenever you make a change to the shape of your state that is not backwards-compatible. This includes adding or removing properties, changing the type of a property, or moving properties around within the state tree (e.g. breaking controllers changes, etc...). - Detecting Errors in a Migration: The best way to detect errors in a migration is through thorough testing. Write tests that take various shapes of old state and ensure that they are correctly transformed into the new state shape. Also, use TypeScript or another type system to help catch type errors. - Handling Migration Errors: If a migration fails, you should have a strategy in place to handle the error. This could be as simple as logging the error and continuing with the default state, or it could involve more complex error recovery logic. In any case, it's important to ensure that your app can still function in some way even if a migration fails. + +- Example: +``` + if ( + phishingControllerState?.hotlistLastFetched && + phishingControllerState?.stalelistLastFetched + ) { + // This will make the list be fetched again when the user updates the app + state.engine.backgroundState.PhishingController.hotlistLastFetched = 0; + state.engine.backgroundState.PhishingController.stalelistLastFetched = 0; + } else { + captureException( + new Error( + `Migration 26: Invalid PhishingControllerState hotlist and stale list fetched: '${JSON.stringify( + state.engine.backgroundState.PhishingController, + )}'`, + ), + ); + } + + return state; +``` + - Keeping Migrations Idempotent: Make sure your migrations are idempotent, meaning they can be run multiple times without changing the result beyond the initial application. This makes migrations safer and easier to test. - Removing Old Migrations: Over time, you may accumulate many migrations. At some point, it may be safe to remove old migrations, especially if you know that all users have migrated to a newer version of the state. Be cautious with this, as removing a migration could break the ability to upgrade for any users who are still on old versions of the state. From bf4c8221d2c129c4ed9754a321c2596332a2fe9d Mon Sep 17 00:00:00 2001 From: sethkfman Date: Fri, 19 Jan 2024 12:57:12 -0700 Subject: [PATCH 4/7] added to ToC --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 680f7d4..3cb7477 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ This is a living repository — nothing is set in stone! If you're member of Met - [Engineering Principles](./docs/engineering-principles.md) - [Guide to Pull Requests](./docs/pull-requests.md) - [JavaScript Guidelines](./docs/javascript.md) +- [Migrations Best Practices](./docs/migrations.md) - [Secure Development Lifecycle Policy](./docs/sdlc.md) - [Secure Coding Guidelines](./docs/secure-coding-guidelines.md) - [TypeScript Guidelines](./docs/typescript.md) From 704d9cff40d581ce7806c821dbe886c79a3d9b45 Mon Sep 17 00:00:00 2001 From: sethkfman <10342624+sethkfman@users.noreply.github.com> Date: Thu, 1 Feb 2024 12:29:06 -0700 Subject: [PATCH 5/7] Update docs/mirgrations.md remove should Co-authored-by: Nico MASSART --- docs/mirgrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mirgrations.md b/docs/mirgrations.md index 1447501..9f620f4 100644 --- a/docs/mirgrations.md +++ b/docs/mirgrations.md @@ -1,6 +1,6 @@ # State Migration Best Practices -These best practices should apply to any team that contributes to an application that leverages local state. +These best practices apply to any team that contributes to an application that leverages local state. ## Best Practices - When to Add a Migration: You should add a migration whenever you make a change to the shape of your state that is not backwards-compatible. This includes adding or removing properties, changing the type of a property, or moving properties around within the state tree (e.g. breaking controllers changes, etc...). From aae08b52db8d797a0a7718b01f4ea8f1d1f516e8 Mon Sep 17 00:00:00 2001 From: sethkfman <10342624+sethkfman@users.noreply.github.com> Date: Thu, 1 Feb 2024 12:30:16 -0700 Subject: [PATCH 6/7] Update docs/mirgrations.md remove should Co-authored-by: Nico MASSART --- docs/mirgrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mirgrations.md b/docs/mirgrations.md index 9f620f4..f568958 100644 --- a/docs/mirgrations.md +++ b/docs/mirgrations.md @@ -3,7 +3,7 @@ These best practices apply to any team that contributes to an application that leverages local state. ## Best Practices -- When to Add a Migration: You should add a migration whenever you make a change to the shape of your state that is not backwards-compatible. This includes adding or removing properties, changing the type of a property, or moving properties around within the state tree (e.g. breaking controllers changes, etc...). +- When to Add a Migration: add a migration whenever you make a change to the shape of your state that is not backwards-compatible. This includes adding or removing properties, changing the type of a property, or moving properties around within the state tree (e.g. breaking controllers changes, etc...). - Detecting Errors in a Migration: The best way to detect errors in a migration is through thorough testing. Write tests that take various shapes of old state and ensure that they are correctly transformed into the new state shape. Also, use TypeScript or another type system to help catch type errors. - Handling Migration Errors: If a migration fails, you should have a strategy in place to handle the error. This could be as simple as logging the error and continuing with the default state, or it could involve more complex error recovery logic. In any case, it's important to ensure that your app can still function in some way even if a migration fails. From 57e1494a3a0228abd0685f2a84b38130da13b529 Mon Sep 17 00:00:00 2001 From: sethkfman <10342624+sethkfman@users.noreply.github.com> Date: Thu, 1 Feb 2024 12:30:33 -0700 Subject: [PATCH 7/7] Update docs/mirgrations.md Remove should and add must Co-authored-by: Nico MASSART --- docs/mirgrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mirgrations.md b/docs/mirgrations.md index f568958..b833f6c 100644 --- a/docs/mirgrations.md +++ b/docs/mirgrations.md @@ -5,7 +5,7 @@ These best practices apply to any team that contributes to an application that l ## Best Practices - When to Add a Migration: add a migration whenever you make a change to the shape of your state that is not backwards-compatible. This includes adding or removing properties, changing the type of a property, or moving properties around within the state tree (e.g. breaking controllers changes, etc...). - Detecting Errors in a Migration: The best way to detect errors in a migration is through thorough testing. Write tests that take various shapes of old state and ensure that they are correctly transformed into the new state shape. Also, use TypeScript or another type system to help catch type errors. -- Handling Migration Errors: If a migration fails, you should have a strategy in place to handle the error. This could be as simple as logging the error and continuing with the default state, or it could involve more complex error recovery logic. In any case, it's important to ensure that your app can still function in some way even if a migration fails. +- Handling Migration Errors: If a migration fails, you must have a strategy in place to handle the error. This could be as simple as logging the error and continuing with the default state, or it could involve more complex error recovery logic. In any case, it's important to ensure that your app can still function in some way even if a migration fails. - Example: ```