diff --git a/1.5-Keeping-Up-To-Date.md b/1.5-Keeping-Up-To-Date.md new file mode 100644 index 0000000..d92746b --- /dev/null +++ b/1.5-Keeping-Up-To-Date.md @@ -0,0 +1,67 @@ +We make a lot of changes - not just adding and deprecating preferences, or flipping them from active to inactive, or changing their values, but also making descriptions better, syntax tweaks, adding/removing references, and even whole section revamps and re-ordering. Doing a file comparison and re-applying your own changes is time consuming and not feasible. + +:small_orange_diamond: The BEST Way To Update (and not lose your changes) + +- **You use the ghacks user.js exactly as it is, no changes.** + * No need to compare files + * Just download and update your user.js by replacing it +- In a `/profile/preferences/` directory, you can store any preference overrides in a separate js file +- Follow our [changelogs](https://github.com/ghacksuserjs/ghacks-user.js/issues?q=is%3Aissue+is%3Aopen+label%3Achangelog) for a super easy read and links. + * We do one per stable release. Old changelogs are archived off under closed issues +- Follow our [deprecated items](https://github.com/ghacksuserjs/ghacks-user.js/issues/123) sticky issue +- You can also follow all the [commits](https://github.com/ghacksuserjs/ghacks-user.js/commits/master) + * Commits per release start with the description "Start XX commits" + * The descriptions should be short but informative (we're getting better at it) +- You can also do compares/diffs between [releases](https://github.com/ghacksuserjs/ghacks-user.js/releases) right here on github + +:small_orange_diamond: Example + +Lets say you don't want to limit fonts and need mathml + +- In your `profile/user.js` (which is the ghacks user.js) you have +```js +/* 1401: disable websites choosing fonts (0=block, 1=allow) ***/ +user_pref("browser.display.use_document_fonts", 0); + +/* 1405: disable WOFF2 (Web Open Font Format) ***/ +user_pref("gfx.downloadable_fonts.woff2.enabled", false); + +/* 2663: disable MathML (Mathematical Markup Language) (FF51+) ***/ +user_pref("mathml.disabled", true); +``` + +- In a `profile/preferences/override.js` (you can use any name except user.js) you can override them +```js +/*** MY OVERRIDES ***/ +user_pref("browser.display.use_document_fonts", 1); // 1401 +user_pref("gfx.downloadable_fonts.woff2.enabled", true); //1405 +user_pref("mathml.disabled", false); // 2663 +``` + +Firefox will apply the `profile/preferences/*.js` file preferences last. The next time you update the `profile/user.js` and replace it, there is no need for you to edit it, and your existing tweaks are already applied and not lost - from the `profile/preferences/override.js`. Now all you need to do is follow the changelog/deprecated-sticky-issue/commits to see what's new, changed, or deprecated/removed + +:small_orange_diamond: Caveats + +You will need to monitor your small set of overrides due to Firefox changes. Just keep an eye on things is all I'm saying + +- Deprecated Items + * A deprecated item will not remove, or comment itself out in your override.js, you will have to do it manually (and reset in about:config to get rid of it, which you would need to do anyway). No harm, it will just not be a pref that does anything anymore. +- Changes to Default Values + * Example `user_pref("security.tls.version.min", 3);` + * You override it with the Firefox default value of `1` + * In the future Firefox changes their default to `2` due to security concerns, but now you're stuck with a value of `1` and you didn't pick up on it +- Hidden Pref Default Values + * Most hidden prefs seem to be boolean (true or false), so these shouldn't be an issue, but not all are. Here's one: `user_pref("extensions.enabledScopes", 1); // (hidden pref)` + * If you right-click and reset in about:config it simply clears itself. What it the default value? If you know it, that's great. If you don't... + * A solution here is to add a section to your override listing prefs to comment out in the user.js and reset in about:config. Just re-apply it on each update. + +```js +/*** MY OVERRIDES ***/ +user_pref("browser.display.use_document_fonts", 1); // 1401 +user_pref("gfx.downloadable_fonts.woff2.enabled", true); //1405 +user_pref("mathml.disabled", false); // 2663 + +/*** MAKE SURE THESE ARE COMMENTED OUT AND RESET ***/ +// 2668: extensions.enabledScopes +``` +