forked from wikimedia/wikipedia-ios
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
43fd8d7
commit 28a7aa2
Showing
2 changed files
with
26 additions
and
62 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,74 +1,38 @@ | ||
| # Wikipedia iOS Web Development | ||
| This document covers setting up your machine for work on the web components of the Wikipedia iOS project. | ||
|
|
||
| ## Setup | ||
| The app uses several web components. This document explains how they are set up and how to update them. | ||
|
|
||
| Similar to the [project's Ruby setup for ci](ci.md), we recommend using a [node version manager](https://github.com/nodenv/nodenv) to install node and manage multiple versions of [node](https://nodejs.org/) on the same machine. | ||
| #### Article View | ||
| The article view uses a server-side response from our [Page Content Service](https://www.mediawiki.org/wiki/Page_Content_Service#/page/mobile-html) with additional local `js` and `css` files for further customizations. These local files live within the `Wikipedia/assets` folder in the project. You can update these directly and commit the changes, with the exception of the `codemirror/resources`, `codemirror/config` and `pcs-html-converter` subdirectories (explained next). | ||
|
|
||
| These are the recommended steps for setting up your machine for web development: | ||
| ##### PCS-HTML-Converter | ||
| These files are only used for users who upgrade from the 6.5.1 release to the 6.6.0 release, where a major migration in the way we display articles was needed. The `pcs-html-converter` files are intended to take legacy saved article html and convert it to our more modern format represented in the mobile-html endpoint, all locally on device. If these files need to be updated to reflect the latest reponse from the server, follow these steps: | ||
|
|
||
| #### Update Submodules | ||
| The web components are included in this repo as a Git submodule called `wikipedia-ios-codemirror`. To fully initialize the submodule, run the script located at `scripts/update_submodules`. | ||
| 1. Clone the [pcs-html-converter](https://github.com/wikimedia/pcs-html-converter) repository. | ||
| 2. Follow the instructions on it's readme to instantiate it's submodule, and fetch and pull the latest from `master` of this submodule. The pcs-html-converter repository has a submodule pointing to our mobile apps repo, which contains the latest output of our mobile-html endpoint. | ||
| 3. Run `npm install` and `npm build` in the pcs-html-converter root directory. | ||
| 4. Copy the newly generated `PCSHTMLConverter.js` and `Polyfill.js` files and replace them in the wikipedia-ios repository, under `Wikipedia/assets/pcs-html-converter/build`. | ||
| 5. The other files within `assets/pcs-html-converter` are simply copied from what the server is serving. Copy the responses from these and paste in the appropriate files: | ||
| - (https://meta.wikimedia.org/api/rest_v1/data/css/mobile/base)[https://meta.wikimedia.org/api/rest_v1/data/css/mobile/base] > base.css | ||
| - (https://meta.wikimedia.org/api/rest_v1/data/css/mobile/pcs)[https://meta.wikimedia.org/api/rest_v1/data/css/mobile/pcs] > pcs.css | ||
| - (https://meta.wikimedia.org/api/rest_v1/data/javascript/mobile/pcs)[https://meta.wikimedia.org/api/rest_v1/data/javascript/mobile/pcs] > pcs.js | ||
| 6. Make a PR into the `wikipedia-ios` with these changes. | ||
|
|
||
| #### Install [homebrew](https://brew.sh) | ||
| [homebrew](https://brew.sh) should have been installed by `scripts/setup`, but if you didn't run that script or would like to manually install it: | ||
| ``` | ||
| /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" | ||
| ``` | ||
| #### Editing View | ||
| The editing view is also a web view, but all files powering it live locally in the project. The files within `Wikipedia/assets/codemirror/resources` and `Wikipedia/assets/codemirror/config` are copied from our separate submodule repository or autogenerated respectively, so they should not be edited directly. Details are below for updating these areas specifically. | ||
|
|
||
| #### Install [nodenv](https://github.com/nodenv/nodenv) | ||
| [nodenv](https://github.com/nodenv/nodenv) manages multiple node versions on the same machine. This is helpful in our environment where other Wikimedia Foundation repositories depend on different node versions. After [homebrew](https://brew.sh) is installed, install [nodenv](https://github.com/nodenv/nodenv) by running: | ||
| ``` | ||
| brew install nodenv | ||
| ``` | ||
| ##### Changing resources files | ||
|
|
||
| #### Update your ~/.bash_profile | ||
| Once the install command completes, add `eval "$(nodenv init -)"` to your `~/.bash_profile` (create this file if it doesn't exist) | ||
| First open a PR in the [wikipedia-ios-codemirror repository](https://github.com/wikimedia/wikipedia-ios-codemirror) repository. Once that is merged, to reflect those changes in this project follow these steps: | ||
|
|
||
| #### Restart Terminal | ||
| After terminal restarts, verify that [nodenv](https://github.com/nodenv/nodenv) is working properly by typing `which node` and verifying it shows a path inside your home folder. | ||
| 1. The `wikipedia-ios` repository has a submodule that points to the `wikipedia-ios-codemirror` repository. `cd` to `Wikipedia/CodeMirror/wikipedia-ios-codemirror`, then pull the latest changes from master. If the `Wikipedia/CodeMirror/wikipedia-ios-codemirror` directory is empty, you can first run the `scripts/update_submodules` script to initalize the submodule. | ||
| 2. From the `scripts` folder, run the `copy_code_mirror_resources` script. This will copy the relevant resources folder from the submodule into the iOS project assets folder. | ||
| 3. Commit your changes and open a PR. | ||
|
|
||
| #### Install the required node version | ||
| First `cd` to the directory where you have this repository: | ||
| ``` | ||
| cd /path/to/your/wikipedia-ios | ||
| ``` | ||
| ##### Generating config files | ||
| We instantiate our CodeMirror editor with configurations that are generated into the `assets/codemirror/config` folder. These files should not be edited directly. You can edit the output of these files inside `Command Line Tools/Update Languages/WikipediaLanguageCommandLineUtility.swift` if needed, then run the `Update Languages` scheme to regenerate these files. | ||
|
|
||
| Then, install the [node](https://nodejs.org/) version specified by our project by running: | ||
| ``` | ||
| nodenv install -s | ||
| ``` | ||
| There are other codemirror files that do not originate from the `wikipedia-ios-codemirror` repository or the languages command line utility (anything in `assets/codemirror`, excluding `/resources` and `config`). These are styles and new functionality specific to the iOS app. These files can be updated directly. | ||
|
|
||
| Verify it was installed by running `node -v` and matching it to the version number specified in the `.node-version` file in this repository. | ||
|
|
||
| #### Install [grunt](http:https://gruntjs.com) | ||
| We use [grunt](http:https://gruntjs.com) to automate tasks related to web development such as dependency management and packaging the sources for [integration into the app](#integrating-web-into-the-native-app). Install [grunt](http:https://gruntjs.com) for your newly installed version of node by running: | ||
| ``` | ||
| npm install -g grunt | ||
| ``` | ||
|
|
||
| Verify that grunt was properly installed by running `which grunt` and verifying it shows a path inside your home folder. If it doesn't, try restarting terminal again or switching to a new terminal tab. | ||
|
|
||
| #### Install node modules | ||
| First `cd` to the directory where you have this repository if you aren't there already: | ||
| ``` | ||
| cd /path/to/your/wikipedia-ios | ||
| ``` | ||
|
|
||
| Next, `cd` to the www folder inside of this repository: | ||
| ``` | ||
| cd www | ||
| ``` | ||
|
|
||
| Next, install the node dependencies (modules) specified by `package.json` by running: | ||
| ``` | ||
| npm install | ||
| ``` | ||
|
|
||
| Finally, run grunt to build the web components of the app: | ||
| ``` | ||
| grunt | ||
| ``` | ||
|
|
||
| ## Process | ||
| When making any changes to web dependencies, you should be working with the files in the `www` folder. Once you are done making changes, run `grunt` inside of that folder to compile your changes into the `Wikipedia/assets` folder. When committing these changes, there will be similar updates to files in both `www` and `Wikipedia/assets`. | ||
| #### Other Views | ||
| There are other smaller web components in the app, such as the About view. These live in the `Wikipedia/assets` folder and can be updated directly. |
File renamed without changes.