This repository has been archived by the owner on Feb 4, 2025. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 37
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update README.md with deprecation notice
- Loading branch information
Showing
1 changed file
with
109 additions
and
120 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,138 +1,127 @@ | ||
| # WordPress-FluxC-Android | ||
| # 🚨 Repository Archived 🚨 | ||
|
|
||
| > [!WARNING] | ||
| > **This repository has been archived** because its functionality has been merged into the two clients that previously used it: the [WordPress/Jetpack app](https://github.com/wordpress-mobile/WordPress-Android) and the [WooCommerce app](https://github.com/woocommerce/woocommerce-ios). Future development will continue within those repositories. | ||
| --- | ||
|
|
||
| <h1 align="center"><img src="docs/images/logo-woocommerce.svg" width="300"><br>for Android</h1> | ||
|
|
||
| <p align="center">A Jetpack-powered mobile app for WooCommerce.</p> | ||
|
|
||
| <p align="center"> | ||
| <a href="https://buildkite.com/automattic/woocommerce-android"> | ||
| <img src="https://badge.buildkite.com/3ac8789ce5bc81e2d078d32ee8e526efbdb7c1ef3b19c70be3.svg?branch=trunk"> | ||
| </a> | ||
| <a href="https://github.com/woocommerce/woocommerce-android/releases"> | ||
| <img alt="Release" src="https://img.shields.io/github/v/tag/woocommerce/woocommerce-android?label=release&sort=semver"> | ||
| </a> | ||
| <a href="https://github.com/woocommerce/woocommerce-android/blob/trunk/LICENSE.md"> | ||
| <img alt="License" src="https://img.shields.io/github/license/woocommerce/woocommerce-android"> | ||
| </a> | ||
| </p> | ||
|
|
||
| WordPress-FluxC-Android is a networking and persistence library that helps to connect and sync data from a WordPress site (self hosted, or wordpress.com site). | ||
| <p align="center"> | ||
| <a href="#setup-instructions">Setup Instructions</a> • | ||
| <a href="#build--test">Build & Test</a> • | ||
| <a href="#-documentation">Documentation</a> • | ||
| <a href="#-contributing">Contributing</a> • | ||
| <a href="#-automation">Automation</a> • | ||
| <a href="#-security">Security</a> • | ||
| <a href="#-need-help">Need Help?</a> • | ||
| <a href="#-resources">Resources</a> • | ||
| <a href="#-license">License</a> | ||
| </p> | ||
|
|
||
| Based on the [Flux][1] pattern, we're using: [Dagger2][2] for dependency injection, [WellSql][3] for persistence. | ||
| ## 🎉 Setup Instructions | ||
|
|
||
| FluxC is pronounced ‘fluxy’, and stands for ‘Flux Capacitor’. This makes a double reference to the architecture model (since a capacitor is a kind of storage unit, or ‘store’). More importantly, a flux capacitor is the core component of the DeLorean time machine in [Back to the Future](https://en.wikipedia.org/wiki/Back_to_the_Future), which ‘makes time travel possible.’ | ||
| 1. Make sure you've installed [Android Studio](https://developer.android.com/studio). | ||
| 1. Clone this repository in the folder of your preference, and then enter that folder: | ||
|
|
||
| **Most of our documentation for using and contributing to FluxC can be found in our [wiki](https://github.com/wordpress-mobile/WordPress-FluxC-Android/wiki).** | ||
| ```bash | ||
| $ git clone https://github.com/woocommerce/woocommerce-android.git | ||
| $ cd woocommerce-android | ||
| ``` | ||
|
|
||
| ## Using FluxC as a library | ||
| 1. Copy `defaults.properties` to the secrets directory: `cp defaults.properties ~/.configure/woocommerce-android/secrets/secrets.properties`. See the [Configuration Files](docs/project-overview.md#configuration-files) section for a breakdown of the properties. | ||
| 1. Generate the developer oauth2 tokens. These values get copied into the `~/.configure/woocommerce-android/secrets.properties` file in the next step. See the [OAuth2 Authentication](docs/project-overview.md#oauth2-authentication) section for details. | ||
| 1. In Android Studio, open the project from the local repository. This will auto-generate `local.properties` with the SDK location. | ||
| 1. Optional: Go to Tools → Device Manager and create an emulated device. | ||
| 1. Run. (Creates a default virtual device if you skipped the previous step) | ||
|
|
||
| Please see our [Using FluxC](https://github.com/wordpress-mobile/WordPress-FluxC-Android/wiki/Using-FluxC#initial-setup) wiki page for setup instructions. | ||
| ## Build & Test | ||
|
|
||
| ## Building the library | ||
| To build, install, and test the project from the command line: | ||
|
|
||
| The gradle build system will fetch all dependencies and generate | ||
| files you need to build the project. You first need to generate the | ||
| local.properties (replace YOUR_SDK_DIR with your actual android SDK directory) | ||
| file and create the gradle.properties file. The easiest way is to copy | ||
| our example: | ||
| ```bash | ||
| $ ./gradlew assembleVanillaDebug # assemble the debug .apk | ||
| $ ./gradlew installVanillaDebug # install the debug apk if you have an | ||
| # emulator or a device connected | ||
| $ ./gradlew :WooCommerce:testVanillaDebugUnitTest # assemble, install and run unit tests | ||
| $ ./gradlew :WooCommerce:connectedVanillaDebugAndroidTest # assemble, install and run Android tests | ||
| ``` | ||
|
|
||
| $ echo "sdk.dir=YOUR_SDK_DIR" > local.properties | ||
| $ cp gradle.properties-example gradle.properties | ||
| $ ./gradlew fluxc:build | ||
| ## 📚 Documentation | ||
|
|
||
| ## Building and running tests and the example app | ||
| - Project Overview | ||
| - [OAuth2 Authentication](docs/project-overview.md#oauth2-authentication) | ||
| - [Configuration Files](docs/project-overview.md#configuration-files) | ||
| - [Using Detekt](docs/project-overview.md#using-detekt) | ||
| - [Google Configuration](docs/project-overview.md#google-configuration) | ||
| - Development Practices | ||
| - [Coding Style Practices](docs/coding-style.md) | ||
| - [Pull Request Guidelines](docs/pull-request-guidelines.md) | ||
| - [Material Theme Designs](docs/material-theme-designs.md) | ||
| - [Using Android Resources](docs/using-android-resources.md) | ||
| - [Localization](docs/localization.md) | ||
| - [Themes & Styling Practices](docs/theming-styling-best-practices.md) | ||
| - [Optimising screens for tablets](docs/supporting-tablets.md) | ||
| - Data | ||
| - [Tracking Events](docs/tracking-events.md) | ||
| - Accessibility | ||
| - [Accessibility Guidelines](docs/accessibility-guidelines.md) | ||
| - [Right to Left Layout Guidelines](docs/right-to-left-layout-guidelines.md) | ||
| - Quality & Testing | ||
| - [Beta Testing](https://woocommercehalo.wordpress.com/setup/join-android-beta/) | ||
| - Features | ||
| - [Feature Flags](docs/feature-flags.md) | ||
|
|
||
| $ cp -a example/properties-example/ example/properties/ | ||
| $ ./gradlew cAT # Regression tests | ||
| $ ./gradlew testDebug # Unit tests | ||
| ## 👏 Contributing | ||
|
|
||
| Note: this uses the default `example/properties/api.properties` file. You'll have to get | ||
| a [WordPress.com OAuth2 ID and secret](#oauth2-authentication). | ||
| Read our [Contributing Guide](CONTRIBUTING.md) to learn about reporting issues, contributing code, and more ways to contribute. | ||
|
|
||
| We have some tests connecting to real HTTP servers, URL and credentials are defined in `example/properties/tests.properties`, you must edit it or obtain the real file to run the tests. | ||
| ## 🔐 Security | ||
|
|
||
| Please note that, unless using special credentials which cannot be shared publicly, some of the WordPress.com connected tests will not pass unless the OAuth2 ID and secret are registered to the account that the test is attempting to log into. | ||
| If you happen to find a security vulnerability, we would appreciate you letting us know at https://hackerone.com/automattic and allowing us to respond before disclosing the issue publicly. | ||
|
|
||
| ## OAuth2 Authentication | ||
| ## 🦮 Need Help? | ||
|
|
||
| To test with your own OAuth2 ID and Secret you will need to create an application or view the details for your existing application with our [WordPress.com applications manager][7]. | ||
| You can find the WooCommerce usage docs | ||
| here: [woocommerce.com/documentation/woocommerce/](https://woocommerce.com/documentation/woocommerce/) | ||
|
|
||
| When creating your application, you should select "Native client" for the application type. The applications manager currently requires a "redirect URL", but this isn't used for mobile apps. Just use "https://localhost". | ||
| General usage and development questions: | ||
|
|
||
| * [WooCommerce Slack Community](https://woocommerce.com/community-slack/) | ||
| * [WordPress.org Forums](https://wordpress.org/support/plugin/woocommerce) | ||
| * [The WooCommerce Help and Share Facebook group](https://www.facebook.com/groups/woohelp/) | ||
|
|
||
| ## 🔗 Resources | ||
|
|
||
| - [Mobile blog](https://mobile.blog) | ||
| - [WooCommerce API Documentation (currently v3)](https://woocommerce.github.io/woocommerce-rest-api-docs/#introduction) | ||
|
|
||
| ## 📜 License | ||
|
|
||
| WooCommerce for Android is an Open Source project covered by the [GNU General Public License version 2](https://github.com/woocommerce/woocommerce-android/blob/trunk/LICENSE.md). | ||
|
|
||
| ## 📚 Proprietary Libraries | ||
|
|
||
| In order to offer a great experience to our users, we use some proprietary libraries that are not open source. These libraries are: | ||
|
|
||
| - [ML Kit](https://developers.google.com/ml-kit) for barcode scanning and text recognition. You can find its Terms of Service [here](https://developers.google.com/ml-kit/terms). | ||
|
|
||
| Once you've created your application in the [applications manager][7], you'll need to edit the `example/properties/api.properties` file and change the `wp.OAUTH.APP.ID` and `wp.OAUTH.APP.SECRET` fields. | ||
|
|
||
| ## Setting up Checkstyle | ||
|
|
||
| The FluxC project uses [Checkstyle](http://checkstyle.sourceforge.net/). You can run checkstyle using `./gradlew checkstyle`. You can also view errors and warnings in realtime with the Checkstyle plugin. When importing the project into Android Studio, Checkstyle should be set up automatically. If it is not, follow the steps below. | ||
|
|
||
| You can install the CheckStyle-IDEA plugin in Android Studio here: | ||
|
|
||
| `Android Studio > Preferences... > Plugins > CheckStyle-IDEA` | ||
|
|
||
| Once installed, you can configure the plugin here: | ||
|
|
||
| `Android Studio > Preferences... > Tools > Checkstyle` | ||
|
|
||
| From there, add and enable the configuration file for FluxC, located at [config/checkstyle.xml](https://github.com/wordpress-mobile/WordPress-FluxC-Android/blob/trunk/config/checkstyle.xml). | ||
|
|
||
| ## Using Detekt | ||
|
|
||
| The FluxC project uses [detekt](https://github.com/detekt/detekt) for Kotlin linting and code style check. | ||
|
|
||
| You can run detekt using `./gradlew detekt`. | ||
|
|
||
| You can also view errors and warnings in realtime with the Detekt plugin. | ||
|
|
||
| You can install the detekt plugin in Android Studio here: | ||
|
|
||
| `Android Studio > Preferences... > Plugins > detekt` | ||
|
|
||
| Once installed, you can configure the plugin here: | ||
|
|
||
| `Android Studio > Preferences... > Tools > Detekt` | ||
|
|
||
| From there, add and enable the custom configuration file, located at [config/detekt/detekt.yml](https://github.com/wordpress-mobile/WordPress-FluxC-Android/blob/trunk/config/detekt/detekt.yml). | ||
|
|
||
| If you want to use the **AutoCorrect** feature of the plugin, make sure that the option `Enable formatting (ktlint) rules` is enabled in the above settings, then you will be able to reformat any file according to detekt's rules using the refactor menu `AutoCorrect by Detekt Rules` | ||
|
|
||
| ## Contributing | ||
|
|
||
| ### Actions | ||
|
|
||
| Each store should have a corresponding enum defining actions for that store. For example, [SiteStore][4]'s actions are defined in the [SiteAction][5] enum. | ||
|
|
||
| Action naming guide: | ||
|
|
||
| FETCH_X - request data from the server | ||
| PUSH_X - send data to the server | ||
| UPDATE_X - local change | ||
| REMOVE_X - local remove | ||
| DELETE_X - request deletion on the server | ||
|
|
||
| Each action enum should be annotated with `@ActionEnum`, with individual actions receiving an `@Action` annotation with an optional `payloadType` setting (see [SiteAction][5] for an example). | ||
|
|
||
| ### Endpoints | ||
|
|
||
| Endpoints for each of the supported APIs are centralized in a generated endpoint file: `WPCOMREST.java` and `XMLRPC.java` (also `WPAPI.java`). | ||
|
|
||
| To add a new endpoint, first add it to the appropriate `fluxc-processor/src/main/resources/*.txt` file, and then rebuild the project to update the generated (Java) endpoint file. | ||
|
|
||
| Note that, for WordPress.com REST API endpoints, the final endpoint will be normalized to include a trailing slash. | ||
|
|
||
|
|
||
| #### Response Models | ||
|
|
||
| Create a class implementing `Response` interface in a corresponding package in `org.wordpress.android.fluxc.network.rest` tree. | ||
|
|
||
| Prefer using nullable types in response models to prevent crashes when the API changes. Map nullable types to non-nullable types (if applicable) when mapping response models to domain models. | ||
|
|
||
|
|
||
| ### On Changed Events | ||
|
|
||
| All On Changed Events extend the OnChanged class. They encapsulate an `error` | ||
| field. Events can be checked for an error by calling `event.isError()`. | ||
|
|
||
| On Changed Events naming guide: | ||
|
|
||
| onXChanged(int rowsAffected) - Keep X singular even if multiple X were changed | ||
| onXRemoved(int rowsAffected) - Keep X singular even if multiple X were removed | ||
|
|
||
| ## Need help to build or hack? | ||
|
|
||
| Say hello on our [Slack][6] channel: `#mobile`. | ||
|
|
||
| ## LICENSE | ||
|
|
||
| WordPress-FluxC-Android is an Open Source project covered by the [GNU General Public License version 2](LICENSE.md). | ||
|
|
||
| [1]: https://facebook.github.io/flux/docs/overview/ | ||
| [2]: https://google.github.io/dagger/ | ||
| [3]: https://github.com/yarolegovich/wellsql | ||
| [4]: https://github.com/wordpress-mobile/WordPress-FluxC-Android/blob/ba9dd84c54b12d53e01dfdb8efb4a18ed8343311/fluxc/src/main/java/org/wordpress/android/fluxc/store/SiteStore.java | ||
| [5]: https://github.com/wordpress-mobile/WordPress-FluxC-Android/blob/ba9dd84c54b12d53e01dfdb8efb4a18ed8343311/fluxc/src/main/java/org/wordpress/android/fluxc/action/SiteAction.java | ||
| [6]: https://make.wordpress.org/chat/ | ||
| [7]: https://developer.wordpress.com/apps/ | ||
| <p align="center"> | ||
| <br/><br/> | ||
| Made with 💜 by <a href="https://woocommerce.com/">WooCommerce</a>.<br/> | ||
| <a href="https://woocommerce.com/careers/">We're hiring</a>! Come work with us! | ||
| </p> |