From 03139c469577b937fff36e73e85bd674a7ccb5e5 Mon Sep 17 00:00:00 2001 From: FelisCatus Date: Sun, 12 Oct 2014 16:00:51 +0800 Subject: [PATCH] Update README.md. Add project architecture overview and translation. --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 70 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 59ac8e8..0c8d9c7 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,81 @@ SwitchyOmega ============ -A proxy extension for Chromium. +Manage and switch between multiple proxies quickly & easily. -Development status -================== +Chromium Extension +------------------ +The project is available as a Chromium Extension. -## Chromium Extension -The project is now usable as a Chromium Extension. - -You can try it on [Chrome Web Store](https://chrome.google.com/webstore/detail/padekgcemlokbadohgkifijomclgjgif) - -## Development Schedule -The project is now in alpha, and still considered unstable. Any feedback is -welcomed. +You can try it on [Chrome Web Store](https://chrome.google.com/webstore/detail/padekgcemlokbadohgkifijomclgjgif), +or grab a packaged extension file for offline installation on the [Releases page](https://github.com/FelisCatus/SwitchyOmega/releases). Please [report issues on the issue tracker.](https://github.com/FelisCatus/SwitchyOmega/issues) -## Build +Development status +------------------ -SwitchyOmega has migrated to use npm and grunt for building. +## PAC generator +This project contains a PAC generating module called `omega-pac`, which handles +the profiles model and compile profiles into PAC scripts. This module is standalone +and can be published to npm when the documentation is ready. + +## Options manager +The folder `omega-target` contains browser-independent logic for managing the +options and applying profiles. Every public method is well documented in the comments. +Functions related to browser are not included, and shall be implemented in subclasses +of the `omega-target` classes. + +`omega-web` is a web-based configuration interface for various options and profiles. +The interface works great with `omega-target` as the back-end. + +`omega-web` alone is incomplete and requires a file named `omega_target_web.js` +containing an angular module `omegaTarget`. The module contains browser-dependent +code to communicate with `omega-target` back-end, and other code retrieving +browser-related state and information. +See the `omega-target-chromium-extension/omega_target_web.coffee` file for an +example of such module. + +## Targets +The `omega-target-*` folders should contain environment-dependent code such as +browser API calls. + +Each target folder should contain an extended `OmegaTarget` object, which +contains subclasses of the abstract base classes like `Options`. The classes +contains implementation of the abstract methods, and can override other methods +at will. + +A target can copy the files in `omega-web` into its build to provide a web-based +configuration interface. If so, the target must provide the `omega_target_web.js` +file as described in the Options manager section. + +Additionally, each target can contain other files and resources required for the +target, such as background pages and extension manifests. + +For now, only one target has been implemented: The Chromium Extension target. +This target allows the project to be used as a Chromium extension in most +Chromium-based browsers. + +However, the project architecture allows more targets to be added in the future. +The first step would be adapting more browsers including Firefox. I don't have +time for that now. Feel free to open a pull request if you want to help. + +## Translation + +All translations are in the `omega-i18n` folder. For now, only `en` \(English\) +and `zh` \(简体中文\) translations are done. If you notice a translation issue +such as typo or bad spelling, please open an issue or a pull request. + +You can also help to translate SwitchyOmega into your language. Just fork the +project and copy the `en` folder to a new folder named the locale code of your +choice. Then edit the `message.json` to provide translations. The file is in +[Chrome Extension Locale-Specific Messages Format](https://developer.chrome.com/extensions/i18n-messages). +Don't forget to open a pull request when you are done translating. + +## Building the project + +SwitchyOmega has migrated to use npm and grunt for building. Please note that +npm 2.x is required for this project. To build the project: @@ -41,7 +97,7 @@ To enable `grunt watch`, run `grunt watch` once in the `omega-build` directory. This will effectively run `grunt watch` in every module in this project. License -======= +------- ![GPLv3](https://www.gnu.org/graphics/gplv3-127x51.png) SwitchyOmega is licensed under [GNU General Public License](https://www.gnu.org/licenses/gpl.html) Version 3 or later.