Bgerstle has uploaded a new change for review. https://gerrit.wikimedia.org/r/202463
Change subject: readme: WIP ...................................................................... readme: WIP Change-Id: I33df4b6b2917063e6e78b228c2f29e901eb153fa --- M Makefile M README.md A docs/cont-integration.md A docs/web-dev.md A docs/working-with-cocoapods.md A docs/working-with-ruby.md 6 files changed, 113 insertions(+), 93 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/apps/ios/wikipedia refs/changes/63/202463/1 diff --git a/Makefile b/Makefile index 7d4142f..7e3862f 100644 --- a/Makefile +++ b/Makefile @@ -70,7 +70,9 @@ #!!!!! get-homebrew: ##Install Homebrew using the bootstrapping script from http://brew.sh - @if [[ ! $$(brew -v 2>/dev/null) =~ "Homebrew" ]]; then \ + @if [[ $$(brew -v 2>/dev/null) =~ "Homebrew" ]]; then \ + echo "Homebrew already installed!"; \ + else \ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"; \ fi @@ -108,34 +110,20 @@ #!!!!! Web dependency management #!!!!! -web: ##Make web assets -web: css grunt - -CSS_ORIGIN = http://bits.wikimedia.org/en.wikipedia.org/load.php?debug=false&lang=en&only=styles&skin=vector&modules= +CSS_ORIGIN = "http://bits.wikimedia.org/en.wikipedia.org/load.php?debug=false&lang=en&only=styles&skin=vector&modules="; WEB_ASSETS_DIR = "Wikipedia/assets" -define get_css_module -curl -s -L -o -endef +cd "Wikipedia/assets/" && { + curl -L -f -o 'styles.css' "${PREFIX}mobile.app.pagestyles.ios" + curl -L -f -o 'abusefilter.css' "${PREFIX}mobile.app.pagestyles.ios" + curl -L -f -o 'preview.css' "${PREFIX}mobile.app.preview" +} -css: ##Download latest stylesheets - @echo "Downloading CSS assets..."; \ - mkdir -p $(WEB_ASSETS_DIR); \ - cd $(WEB_ASSETS_DIR); \ - $(get_css_module) 'styles.css' "$(CSS_ORIGIN)mobile.app.pagestyles.ios" > /dev/null; \ - $(get_css_module) 'abusefilter.css' "$(CSS_ORIGIN)mobile.app.pagestyles.ios" > /dev/null; \ - $(get_css_module) 'preview.css' "$(CSS_ORIGIN)mobile.app.preview" > /dev/null NODE_VERSION = "$(shell node -v 2>/dev/null)" NPM_VERSION = "$(shell npm -version 2>/dev/null)" -grunt: ##Run grunt -grunt: npm - @cd www && grunt && cd .. - -npm: ##Install Javascript dependencies -npm: node-check - @cd www && npm install && cd .. +npm: ##TODO, run npm install get-node: ##Install node via Homebrew brew install node diff --git a/README.md b/README.md index e43452d..3364346 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ -Wikipedia for iOS ------ +# Wikipedia iOS +The official Wikipedia iOS client. -# Meta * OS target: iOS 6.0 or higher * Device target: iPhone, iPod, iPad * License: MIT-style @@ -14,88 +13,61 @@ * IRC chat: #wikimedia-mobile on irc.freenode.net * Team page: https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/iOS -# Setup -Because of the nature of the project (read: lots of HTML), we have several layers of dependencies. Having said that, we have automated much of the setup so it's not too bad to set the project up and start contributing. +## Development Team +The app is primarily being developed by the Wikimedia Foundation's [Mobile Apps team](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team), starting at the end of October 2013. We maintain iOS specific documentation [here](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/iOS). IRC is the best way to chat with us during Eastern and Pacific business hours (`#wikimedia-mobile` channel on freenode). -Specifically, many tasks have been implemented in the `Makefile`. Run `make` or `make help` to see a list of available tasks (or targets). For instance, simply run `make build-sim` to see if your machine is setup and ready to go. +## Building and Running +This project requires [Xcode 6](https://itunes.apple.com/us/app/xcode/id497799835) or higher. The easiest way to get it is from the [App Store](https://itunes.apple.com/us/app/xcode/id497799835?mt=12), but you can also download it from [developer.apple.com](https://developer.apple.com/) if you have an AppleID registered with an Apple developer account. -Read on to get started… +Once you have Xcode, you should be able to open `Wikipedia.xcworkspace` and run the app on the iOS Simulator (using the **Wikipedia** scheme and target). If you encounter any issues, please don't hesitate to let us know via a bug report or bugging us on IRC. -## Dependencies - -### Before you start -#### Homebrew -Many of the dependencies below are installed easiest via [Homebrew](http://brew.sh). it is recommended that you install it before proceeding. If you run into issues installing dependencies with homebrew, run `brew doctor` to get hints on how to fix them. -#### Bundler -[Bundler](http://bundler.io/) is optional, but **required** for using the Make File and is recommended for installing CocoaPods, along with any other RubyGem dependencies declared in the project's `Gemfile`. -#### Make File -Once Bundler is installed, you can run `make get-deps` to check for the dependencies below (it will also install any gems and pods for you automatically) - -### Build Dependencies -These tools are needed for building and running the app. -- [Xcode 6 or higher](https://itunes.apple.com/us/app/xcode/id497799835) on Mac OS X, available on the App Store or [developer.apple.com](https://developer.apple.com/) after signing in with your Apple ID. -- [Ruby](https://www.ruby-lang.org/en/): comes bundled with OS X (this project only requires the system version). -- [CocoaPods](cocoapods.org) is a Ruby gem that the project uses to download and integrate third-party iOS components. -- [NodeJS](https://nodejs.org): The web assets which are bundled in the app are built using a Node toolchain, specifically [grunt](http://gruntjs.com) which is installed using [npm](npmjs.com). -- [ImageMagick](http://www.imagemagick.org) and [Ghostscript](http://www.ghostscript.com): We generate environment specific icons at build time using these tools. You can install them via homebrew by running `brew install imagemagick` and `brew install ghostscript`, respectively. - -### Patch Submission Dependencies -These tools are required when you intend on submitting a patch. -- [uncrustify](http://uncrustify.sourceforge.net) for formatting source code to conform to our [Style Guide](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/iOS/ObjectiveCStyleGuide). You can install it using homebrew by running: `brew install uncrustify`. -> _[BBUncrustifyPlugin](https://github.com/benoitsan/BBUncrustifyPlugin-Xcode) is an easy way to uncrustify files within the Xcode UI. You can install it from source or by first installing [Alcatraz](http://alcatraz.io)_ - -### CI Dependencies -These tools are required if you want to work on the build system. -- Xcode Command Line Tools: You can install via the Xcode UI or run `xcode-select --install` in Terminal. You can find instructions online for downloading the them via Xcode or the Apple developer portal. -- [Fastlane](https://github.com/KrauseFx/fastlane) is a Ruby gem that automates build tasks. We use Fastlane in conjunction with [Jenkins](https://jenkins-ci.org) to support our [continuous integration workflow](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/iOS/CI). - -### Advanced Tools -These tools are for managing multiple environments and dependencies. If you plan on modifying Pods or need this project's dependencies to coexist along side other projects, try these: -- [rbenv](https://github.com/sstephenson/rbenv) is nice for managing mulitple Ruby versions. -- [nodenv](https://github.com/OiNutter/nodenv) is recommended for managing multiple node versions. - -## Building -Once all the dependencies are installed, you can run from build the following ways: -- **Xcode UI** - just open the `Wikipedia.workspace` file and click build. -- **xcodebuild** - you can build from the command line with the Apple provided tool. -- **Make file** - just type `make build-sim` in the Terminal and it will compile the project for the iOS simulator. -- **Fastlane** - just type `fastlane lane_name` to build the app for the specified lane. - -### Problems? -If you are unable to build, please file a bug and/or contact us via IRC or email. See the top of this file for our contact information. Please include any console logs and/or Xcode screenshots along with a description of your environment. - -## Running -Use Xcode to run the **WikipediaDebug** scheme and target for the destination of your choosing (i.e. simulator or device). Keep in mind that you'll need to provision iOS hardware with an active [developer account](https://developer.apple.com/devcenter/ios/index.action) in order to build and run the app on a device. +## Development +### Architecture +*TODO: We hope to have some high-level documentation on the application's architecture soon.* +### Best practices and coding style +You can find our current thinking on [iOS best practices](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/iOS/BestPractices) and [coding style](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/iOS/ObjectiveCStyleGuide) on our [team page](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/iOS). The [WMFCodingStyle](./WikipediaUnitTests/WMFCodingStyle.h) files are also canonical examples of our coding style, which are enforced using [uncrustify](#uncrustify). +### Dependencies +We use [CocoaPods](#cocoapods) to manage third-party native dependencies and [npm](#npm) for web. You shouldn't need to run either of these tools to build, run, or modify the application source, but if you do, refer to the sections below to get set up. ## Testing -Use the Xcode **Product -> Test** menu-bar action (or `Cmd + U` for hotkey fanatics) to run the **WikipediaUnitTests** target in any scheme. Tests can also be executed from the command line by running `make test`. +The **Wikipedia** scheme is configured to execute the project's iOS unit tests, which can be run using the `Cmd+U` hotkey or the **Product->Test** menu bar action. In addition to unit testing, we enforce our coding style using [uncrustify](#uncrustify). You can also use the project's [Makefile](#makefile) to run both in one action: `make verify`. -# Filing Bugs -Please file bugs on [Phabricator](https://phabricator.wikimedia.org/project/profile/782/) and be sure to use the `Wikipedia-App-iOS-App ` tag. +## Contributing +If you're interested in contributing to the project, you can find our current product, bug, and engineering backlogs on the [iOS App Phabricator project board](https://phabricator.wikimedia.org/project/profile/782/). Once you pick a task, make sure you assign it to yourself to ensure nobody else duplicates your work. -# Submitting patches -Before submitting a patch be sure to use Uncrustify to format your code (See installation instructions above). +Before submitting changes for review, please be sure to use [uncrustify](#uncrustify) to lint the code and [run the unit tests](#testing). Now that the code is lint-free and the new tests (you did add tests, right?) it's time to submit the changes for review! -> _To ease the process, you can install a pre-push hook by running the script ```/scripts/setup_git_hooks.sh``` or by using the BBUncrustifyPlugin as mentioned above._ +### Gerrit +Gerrit is our main vehicle for reviewing and merging code. You'll need to: -See [mediawiki.org's Gerrit page](https://www.mediawiki.org/wiki/Gerrit) for general information about contributing to Wikimedia project source code hosted in Gerrit -- use the project name "apps/ios/wikipedia" in place of "mediawiki/core" etc. +- [Create an SSH key](https://help.github.com/articles/generating-ssh-keys/) +- [Create a wikimedia developer account](https://wikitech.wikimedia.org/wiki/Special:UserLogin/signup) +- Clone the gerrit repo: `git clone ssh://<wikimedia-dev-username>@gerrit.wikimedia.org:29418/apps/ios/wikipedia.git` +- [Install git-review](https://www.mediawiki.org/wiki/Gerrit/git-review) +- Make some changes... +- Squash them into one commit (following our [commit subject and message guidelines](https://www.mediawiki.org/wiki/Gerrit/Commit_message_guidelines)) +- Submit your commit review: `git review` + - You should see a URL pointing your patch on [gerrit.wikimedia.org](https://gerrit.wikimedia.org) +- Add two or more of the [team members](#development-team) as reviewers for your patch -You can also follow or fork from our [GitHub mirror](https://github.com/wikimedia/apps-ios-wikipedia). Note that pull requests submitted through GitHub must be manually copied over to Gerrit for review and merge (though there is a bot we plan to enable to simplify this). +### GitHub +You can also follow or fork from our [GitHub mirror](https://github.com/wikimedia/apps-ios-wikipedia) (which you're probably looking at right now). Note that pull requests submitted through GitHub must be squashed and [submitted as a patch in Gerrit for review and merge](#gerrit). We're trying to think of ways to streamline this process. -Please include unit tests with any new code where possible. +## Development Dependencies +While typical application development is optimized to have as few dependencies as possible (i.e. cloning, building, and running should "Just Work"), certain development and maintenance tasks will require the installation of specific tools. Many of these tools are installable using [Homebrew](http://brew.sh), which our recommended package manager. -# Architecture -This generation of the Wikipedia app is built around native UI chrome (menus, toolbars, search UI, preferences, caching, etc) to improve startup time, responsiveness and "nativey" look-n-feel versus a previous HTML-based approach using PhoneGap/Apache Cordova. +> **Homebrew and many other tools require the Xcode command line tools, which can be installed by running `xcode-select --install` on newer versions of OS X. They can also be installed via Xcode or downloaded from the [Apple Developer downloads page](https://developer.apple.com/downloads) on older versions of OS X.** -The majority of app logic and UI will be in the native layer; we expect to use the WebView component as a relatively dumb content display & event trigger layer. +### Uncrustify +As mentioned in [best practices and coding style](#best-practices-and-coding-style), we use [uncrustify](http://uncrustify.sourceforge.net/) to lint the project's Objective-C code. Installation via Homebrew is straightforward: `brew install uncrustify`. We've also provided a pre-push git hook which automatically lints the code before pushing, which can be installed by running `./scripts/setup_git_hooks.sh`. -# Development team -The app is primarily being developed by the Wikimedia Foundation's [Mobile Apps team](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team), starting at the end of October 2013. We maintain iOS specific documentation [here](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/iOS). The team operates on an "agile"-style process with 2-week sprints and daily stand-ups on at 10:15am US Pacific Time. +> [BBUncrustifyPlugin](https://github.com/benoitsan/BBUncrustifyPlugin-Xcode) is an easy way to uncrustify files within the Xcode UI. You can install it from source or using [Alcatraz](http://alcatraz.io), the unofficial Xcode package/plugin manager. -Volunteer contributions are welcome! +### CocoaPods +[CocoaPods](cocoapods.org) is a Ruby gem that the project uses to download and integrate third-party iOS components (see `Podfile` for an up-to-date list). We have committed all of these dependnecies to the repository itself, removing the need to install the gem or run before building the project. However, if you want to do anything related to CocoaPods (such as upgrading the version of CocoaPods or adding a dependency), please refer to the [Working With Cocoapods documentation](docs/working-with-cocoapods.md). -We can be reached during Eastern and Pacific office hours (and sometimes outside them) in IRC: #wikimedia-mobile on irc.freenode.net. +### NPM +[npm](npmjs.com) is a package manager for [nodejs](nodejs.org). With it, we install various node modules as Javascript dependencies and development tools (see `www/package.json` for an up-to-date list). Similar to our native dependencies, we have committed certain files to the repository to remove node and npm as build dependencies in an effort to streamline typical application development. Please see [Wikipedia iOS Web Development](docs/web-dev.md) for more information about how to work with the web components in this project. -# Previous Source -This is a native rewrite of the original [Wikipedia reader application](https://www.mediawiki.org/wiki/Wikimedia_Apps/Wikipedia) for iOS. - +## Continuous Integration +This is still a work in progress. See [Wikipedia iOS Continuous Integration](docs/cont-integration.md) for more information. diff --git a/docs/cont-integration.md b/docs/cont-integration.md new file mode 100644 index 0000000..65f9824 --- /dev/null +++ b/docs/cont-integration.md @@ -0,0 +1,17 @@ +# Wikipedia iOS Continuous Integration +This document describes the dependencies for working on continuous-integration-related aspects of the Wikipedia iOS project (automated building, testing, deployment, etc). + +## Prerequisites +- Xcode command line tools (see Development Dependencies section in the `README`) +- [Ruby](docs/working-with-ruby.md) + +## Quick Start +Install the aforementioned dependencies (including running `bundle install` to download all required RubyGems), and you should be able to run any of the tasks defined in `fastlane/Fastfile`. Read on for more information about `fastlane` and the other tools we use as part of our CI pipeline. + +## Fastlane +[Fastlane](https://github.com/KrauseFx/fastlane) is a Ruby gem that automates build tasks. We use it in conjunction with [Jenkins](https://jenkins-ci.org) to support our [continuous integration workflow](https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/iOS/CI). + +_TODO: write a high-level overview of the "lanes" defined in Fastfile._ + +[ImageMagick](http://www.imagemagick.org) and [Ghostscript](http://www.ghostscript.com) are used to generate lane-specific specific icons at build time. You can install them via Homebrew by running `brew install imagemagick ghostscript`. You can also install all of the Homebrew formula used by the project using `make brew-install`. + diff --git a/docs/web-dev.md b/docs/web-dev.md new file mode 100644 index 0000000..076bd93 --- /dev/null +++ b/docs/web-dev.md @@ -0,0 +1,19 @@ +# Wikipedia iOS Web Development +This document describes how the project is set up for web development, including dependency management and how web sources are bundled with the app. + +> **NOTE:** The files generated by `grunt` **are committed to the repo** to streamline the native development workflow. When modifying any web-related aspects of the app, be sure to commit both your changes and the generated files. We hope to eventually look into ways to make the web packaging and integration more flexible and reliable. + +## Prerequisites +The web assets are developed with a [NodeJS](https://nodejs.org) toolchain. Node is available via Homebrew, but please be sure to install the version declared in `.node-version`. Similar to the [project's Ruby setup](docs/working-with-ruby.md), the web portion uses a version file which can be picked up by a node version manager such as [nodenv](https://github.com/OiNutter/nodenv). This the recommended way to install and manage node installations. + +Node package dependencies are managed by [npm](npmjs.com). See `package.json` for detailed information about the node dependencies. + +## Tasks +We use [grunt](http://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). A brief overview of the tasks is provided below, but refer to the `Gruntfile` for detailed and up-to-date information. + +### Testing +We use [jshint](http://jshint.com/) to lint the code. Eventually we'll use something like mocha or qunit to test it too... + +## Integrating Web Into The Native App +_TODO: describe how it's integrated_ + diff --git a/docs/working-with-cocoapods.md b/docs/working-with-cocoapods.md new file mode 100644 index 0000000..0a7a9a5 --- /dev/null +++ b/docs/working-with-cocoapods.md @@ -0,0 +1,15 @@ +# Working With CocoaPods +This document is meant to brief developers who need to modify the Wikipedia iOS project's CocoaPods setup. In it, you'll find information on how to setup your machine to work with Ruby gems and CocoaPods, as well as information about how the project is configured with CocoaPods. + +## Prerequisites +- Xcode command line tools + - verify they're installed and up to date: `make xcode-cltools-check` + - if that fails, you might need to update Xcode and/or install the command line tools via `make get-xcode-cltools` +- [Ruby](docs/working-with-ruby.md) + +## Installing the CocoaPods RubyGem +The recommended method is to use Bundler to install all the gems required by the project by running `bundle install`. There's also a `Makefile` goal: `make bundle-install`. The reason this is the recommended method is to guarantee that all developers are using the same version of CocoaPods while gaining the same benefits of using Bundler mentioned in [Working With Ruby](docs/working-with-ruby.md). + +## Updating To A New Verison Of CocoaPods +Simply modify the version specifier in the `Gemfile` and re-install it using Bundler as described in [Installing the CocoaPods RubyGem](#installing-the-cocoapods-rubygem). + diff --git a/docs/working-with-ruby.md b/docs/working-with-ruby.md new file mode 100644 index 0000000..2780aec --- /dev/null +++ b/docs/working-with-ruby.md @@ -0,0 +1,9 @@ +# Working With Ruby +The project only depends on the default Ruby installation of OS X. This is codified in the `.ruby-version` file, which is enforced by [Bundler](http://bundler.io/) and picked up by Ruby version managers such as [rbenv](https://github.com/sstephenson/rbenv). Tools like rbenv and rvm are recommended if you are working on projects which depend on different versions of Ruby. + +## Gems +### Installation +Any gems that the project uses are added to the `Gemfile`, which is used by Bundler to install gems _locally_, inside the project directory. This is done for two reasons. First, to prevent any side effects caused by depending or installing gems globally. Second, to remove any possible need for `sudo` when installing gems. As such, installing gems globally is **not** recommended, nor is using `sudo` to install gems into the OSX-provided Ruby enviroment. + +### Usage +Invoking any of the gems installed by Bundler can be done a couple of different ways. The most reliable way is by using `bundle exec` to prefix your commands (e.g. `bundle exec pod install`). If this is too cumbersome, you can use the `Makefile` goals (e.g. `make pod` which runs `bundle exec pod install`), or configure your `PATH` to discover the local binaries installed by Bundler. -- To view, visit https://gerrit.wikimedia.org/r/202463 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I33df4b6b2917063e6e78b228c2f29e901eb153fa Gerrit-PatchSet: 1 Gerrit-Project: apps/ios/wikipedia Gerrit-Branch: master Gerrit-Owner: Bgerstle <bgers...@wikimedia.org> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
