From 4b972d14febbafff57785a61c6e2331b80b805db Mon Sep 17 00:00:00 2001 From: Jamon Holmgren Date: Sun, 23 Apr 2017 17:21:16 -0700 Subject: [PATCH] Adds Tour of Ignite documentation, updates other docs Also removes old testRelease.sh script --- .github/CONTRIBUTING.md | 13 +- README.md | 1 + bin/testRelease.sh | 175 ------------------ docs/README.md | 1 - docs/advanced-guides/how-to-contribute.md | 77 -------- docs/advanced-guides/tour.md | 70 +++++++ .../using-development-build.md | 36 +--- 7 files changed, 93 insertions(+), 280 deletions(-) delete mode 100755 bin/testRelease.sh delete mode 100644 docs/advanced-guides/how-to-contribute.md create mode 100644 docs/advanced-guides/tour.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index d0ce1c56c..640d3ea9b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -14,9 +14,14 @@ Before submitting a pull request, you will want to make sure that your branch me * Code is compliant with StandardJS (`npm run lint` or `yarn lint`) * Branch has already been [synced with the upstream repo](https://help.github.com/articles/syncing-a-fork/) and any merge-conflicts have been resolved. +## Requirements + +* Node 7.6+ +* NPM 4 (ships with Node 7) + ## Getting Started -1. Clone the repo (`git clone git@github.com:infinitered/ignite.git`) +1. Fork and then clone the repo (`git clone git@github.com:/ignite.git`) 2. CD into the directory (`cd ignite`) 3. Uninstall npm version (`npm u -g ignite-cli && npm u -g react-native-ignite`) 4. Pull all package dependencies (`npm i && npm run bootstrap`) @@ -30,10 +35,16 @@ $ ignite --version 2.0.0-beta.x $ which ignite /usr/local/bin/ignite +$ ignite new UberForHeadLice +... ``` Now you're ready to check out a new branch and get hacking on Ignite! +## Source Code + +To get familiarized with Ignite's source code, read the [Tour of Ignite's source code](../docs/advanced-guides/tour.md). + ## How to Build and Run App Note that if you do not already have the React Native command line tools installed, you should run `npm install -g react-native-cli` or `yarn global add react-native-cli`. For additional information and troubleshooting go to the [React Native Getting Started Guide](https://facebook.github.io/react-native/docs/getting-started.html#content). diff --git a/README.md b/README.md index 7c74ef198..14528e68a 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,7 @@ If you run into problems, first search the issues in this repository. If you don ## :telescope: Where to Go From Here :telescope: #### [Contribute to Ignite](https://github.com/infinitered/ignite/blob/master/.github/CONTRIBUTING.md) - Getting up and running for your first pull request +#### [Take a tour of Ignite source code](https://github.com/infinitered/ignite/blob/master/docs/advanced-guides/tour.md) #### [Chat with us on the IR Community](http://community.infinite.red) - Infinite Red devs standing by #### [Who are We?](https://infinite.red) - Learn More About Infinite Red #### [Project Web Page](https://infinite.red/ignite/) - Ignite on Infinite Red diff --git a/bin/testRelease.sh b/bin/testRelease.sh deleted file mode 100755 index ec6099e08..000000000 --- a/bin/testRelease.sh +++ /dev/null @@ -1,175 +0,0 @@ -#! /bin/bash - -echo 'testRelease.sh is no longer supported' -exit 1 - -#################### Running this Script ####################### -# Verify Git status is clean -# Verify current git is what you're testing -# Run this with `./testRelease.sh ` -# -# If you'd like to test Ignite against FB Master branch -# Run with 2nd param latest `./testRelease.sh fb_check latest` -################################################################ -if [[ -z $1 ]]; then - echo 'Must pass release version as parameter' - exit 1 -fi - -SOMETHING_FAILED=0 -echo "#########################################################" -echo '# Test a release of Ignite before actually releasing it #' -echo '# ._______. #' -echo '# | \ / | #' -echo '# .--|.O.|.O.|______. #' -echo '# __).-| = | = |/ \ | #' -echo "# >__) (.'---\`.)Q.|.Q.|--. #" -echo '# \\___// = | = |-.(__ #' -echo "# \`---'( .---. ) (__< #" -echo "# \\\\.-.// #" -echo "# \`---' #" -echo '#########################################################' - -# Runs command and on failure turns on the SOMETHING_FAILED flag -function test_command { - "$@" - local status=$? - if [ $status -ne 0 ]; then - echo "👎 👎 👎 👎 👎 👎 👎 👎 - $1 Failed" >&2 - SOMETHING_FAILED=$1 - fi - return $status -} - -fire_drill() -{ - echo '~~~🌟 Running Fire Drill' - test_command ./fireDrill.sh -} - -setup() -{ - echo '~~~🌟 Linking local for Testing' - cd ignite-generator - test_command npm link - cd ../ignite-cli - test_command npm link - cd ../ - mkdir testgrounds - cd testgrounds - # Check flag to see if we're testing RN latest against FB latest - if [[ $2 = "latest" ]]; then - echo '~~~🌟 Testing Master vs Facebook Latest' - test_command npm install -g react-native-cli - test_command ignite n TestProj --branch master --latest - else - echo '~~~🌟 Setting up branch' - git branch -d test_$1 - git checkout -b test_$1 - git push origin test_$1 - - echo '~~~🌟 Creating project from branch' - test_command ignite n TestProj --branch test_$1 - fi - - cd TestProj -} - -verify_code() -{ - echo '~~~🌟 Checking Code' - test_command standard App/ - test_command npm test -} - -check_builds() -{ - echo '~~~🌟 Checking Builds' - if [ ! -d "android" ]; then - echo 'Android folder did not generate' - SOMETHING_FAILED=1 - fi - - if [ ! -d "ios" ]; then - echo 'ios folder did not generate' - SOMETHING_FAILED=1 - fi - - echo '~ Build ios' - test_command react-native bundle --entry-file index.ios.js --bundle-output test.ios.js - - echo '~ Build android' - # A failed android build will not exit with a non-zero return! - # This makes it a bit trickier to test for - look for the fail message instead - cd android - ./gradlew assembleRelease | grep -q 'BUILD FAILED' - if [[ $? -eq 0 ]]; then - echo 'Android build failed' - SOMETHING_FAILED=1 - fi - cd - -} - -clean_up() -{ - echo '~~~🌟 Cleanup' - cd ../../ - rm -rf testgrounds - if [[ -z $2 ]]; then - git checkout - - git branch -d test_$1 - git push origin --delete test_$1 - fi -} - -check_generators() -{ - echo '~~~🌟 Running Generator Tests' - # Note to future self: You can add more generator:locations to this list! - declare -a params=('component:components' 'container:containers' 'screen:containers' 'saga:sagas' 'redux:redux') - - # Loop through the generators array and create the files - for i in "${params[@]}" - do - #This will work in BASH, not sure about other shells, though. - IFS=':' read -a split <<< "${i}" - test_command ignite g ${split[0]} tester${split[0]} - done - - # Then make sure they've arrived. - for i in "${params[@]}" - do - IFS=':' read -a split <<< "${i}" - if [ ! -f 'App/'${split[1]}/'tester'${split[0]}*'.js' ]; then - echo '👎 👎 👎 👎 👎 👎 👎 👎' ${split[0]} 'testing failed:' ${split[0]} 'js file was not generated in' ${split[1]} 'folder.' - SOMETHING_FAILED=1 - fi - # Check styles for certain types - if [[ '${split[0]}' == 'component' || '${split[0]}' == 'container' || '${split[0]}' == 'screen' ]]; then - if [ ! -f 'App/'${split[1]}'/Styles/tester'${split[0]}'Style.js' ]; then - echo '👎 👎 👎 👎 👎 👎 👎 👎' ${split[0]} ' testing failed:' ${split[0]} 'style file not generated in' ${split[1]} 'folder.' - SOMETHING_FAILED=1 - fi - fi - done -} - -# This is where the magic happens -fire_drill -setup $1 $2 -verify_code -check_generators -check_builds -clean_up $1 $2 - -# Done -if [ "$SOMETHING_FAILED" != "0" ]; then - echo "~~~👎 Done with errors" 1>&2 - echo "$SOMETHING_FAILED" - exit 1 -else - echo "~~~👍 Everything looks good!" - # depends on $SECONDS being part of sh - printf '%dh:%dm:%ds\n' $(($SECONDS/3600)) $(($SECONDS%3600/60)) $(($SECONDS%60)) - exit 0 -fi diff --git a/docs/README.md b/docs/README.md index 72a123de0..2013e0383 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,6 @@ * [Creating project plugins](./advanced-guides/creating-project-plugins.md) * [Creating boilerplates](./advanced-guides/creating-boilerplates.md) * [Creating generators](./advanced-guides/creating-generators.md) -* [How to Contribute](./advanced-guides/how-to-contribute.md) * [Using development build](./advanced-guides/using-development-build.md) * Writing tests for plugins * Releasing plugins diff --git a/docs/advanced-guides/how-to-contribute.md b/docs/advanced-guides/how-to-contribute.md deleted file mode 100644 index 333005cf0..000000000 --- a/docs/advanced-guides/how-to-contribute.md +++ /dev/null @@ -1,77 +0,0 @@ -# How to Contribute to Ignite - -First, thanks for reading this. - -This is the quick & dirty version on how to get your development environment setup and ready for submitting pull requests to Ignite. - -As you would expect, the `master` branch is Ignite's production branch. When you fork this repo, you can open pull requests against `master`. This is all common practice open source development, nothing surprising here. - -## Requirements - -* Node 7.6+ -* NPM 4 (ships with Node 7) - -## Getting Started - -Head over to [https://github.com/infinitered/ignite](https://github.com/infinitered/ignite) and hit that shiny Fork button in the top right. - -Next clone it and setup the dependencies. - -```sh -git clone git@github.com:YOUR_GITHUB_USERNAME/ignite.git -cd ignite -npm install -npm run bootstrap -``` - -Sweet. - -We now need to make the `ignite` command available globally. Usually end users will type `npm i -g ignite-cli` but we've chosen a hard life for ourselves as developers so a few more steps are required. - -We must use `npm link`. - -```sh -cd packages/ignite-cli -npm link -``` - -If you got an error, you probably have an older version of ignite installed. - -If it was Ignite 1.0, `npm rm -g react-native-ignite` will sort you out. - -If it was an earlier version of 2.0, then `rm /usr/local/bin/ignite && rm /usr/local/lib/node_modules/ignite` is what you want. - -## Did it work? - -Go to a brand new directory: - -```sh -cd ~ -mkdir fun -cd fun -ignite new UberForHeadLice -``` - -Answer a few questions and you're half way to disrupting the Grade 1 scalp hygiene industry. - -Did it fail? Come find us on our Slack at [http://community.infinite.red](http://community.infinite.red) in the #ignite channel. - -For now, you can expect the version number to say 0.2.0. I'm currently working on the build script and will bump this back up to 2.0.0-beta.1 (etc) when were ready. Today or tomorrow! Sorry for the confusion. - - -## Important Directories - -Ignite 2.0 lives under the `packages` directory. We also have `package.json` and `lerna.json` in the root directory. - -:rotating_light::rotating_light::rotating_light: Everything else is Ignite 1.0. Why keep it? Well, a step in the install process of Ignite 1.0 downloads our repo to use the base files. So, we're going to keep those around until 2.0 launches. Sorry about that. Feel free to open your text editor starting at `packages` if you don't like the noise. :rotating_light::rotating_light::rotating_light: - -Under the `packages` directory, you'll see: - -* `ignite-cli` - this is the entry point. It's the CLI, the core commands, and the main infrastructure. -* `ignite-ir-boilerplate` - this is our recommended boilerplate. It's what you get when you run `ignite new SweetApp`. -* `ignite-dev-screens` - A set of awesome developer-facing screens to help you build your app. -* `ignite-integration-tests` - a set of end-to-end tests which ensures things stay working. - -## Debugging - -As we iron out the kinks, you might find that passing `--debug` (as in `ignite new Thing --debug`) might help debugging things. diff --git a/docs/advanced-guides/tour.md b/docs/advanced-guides/tour.md new file mode 100644 index 000000000..a43504b35 --- /dev/null +++ b/docs/advanced-guides/tour.md @@ -0,0 +1,70 @@ +# Tour of Ignite source code + +Ignite's source looks a tad intimidating at first, but it's actually quite straightforward once you get some experience moving around in it. Let's take a tour. + +(note in any code examples we're using `yarn` ... you can substitute `npm` alternative commands if desired) + +## Lerna & "packages" + +Ignite is composed of a few "packages" (in the `./packages` folder). You can think of these packages as mini npm packages, all controlled by a nice tool called [Lerna](https://lernajs.io/). This allows us to split up Ignite into separate packages while not having to coordinate releases across multiple repos and npm versions. + +All you really need to know about Lerna for these purposes is that you can run this from the main folder: + +```sh +$ yarn run bootstrap +``` + +![image](https://cloud.githubusercontent.com/assets/1479215/25318334/12209eaa-2841-11e7-926d-f26113dbefb9.png) + +This will automatically run `yarn` in each of the separate packages, which each has its own `node_modules` folder. + +## gluegun + +`ignite-cli` (described [next](#ignite-cli)) uses another Infinite Red npm package called [gluegun](https://github.com/infinitered/gluegun). Gluegun is sort of like [Yeoman](http://yeoman.io/) in that it gives us a bunch of CLI tools, but it's much lighter and doesn't take over your whole CLI. + +Whenever you see `context` in `ignite-cli`, it is a gluegun runtime context. This is a JS object that has a bunch of useful functions and properties attached to it, like `print` and `parameters`. + +In addition, Ignite adds some of its own Ignite-specific functions and parameters to `context` ... those are found under `context.ignite`. + +If you're curious what's in the context object, check out Gluegun's [nice context docs](https://infinitered.github.io/gluegun/#/context-api.md), or just inspect it with `console.dir(context, {depth: 3, colors true})`. + +## ignite-cli + +This is the CLI part of Ignite which runs under your local node. The `ignite` binary itself is in the `bin` folder and there are some initial scripts that run whenever you invoke `ignite` in the `./src/cli` folder. + +#### Commands + +The commands you can run with Ignite, such as `ignite add `, `ignite doctor`, `ignite new MyApp`, all execute the corresponding JS files under `./src/commands`. Take a peak in each of those files. When you see a function like this: + +```javascript +module.exports = async function (context) { + const { print, filesystem, prompt, ignite, parameters, strings } = context + // ... +} +``` + +... then you're looking at the main function. The `context` object is described above in the [gluegun section](#gluegun). Here, we're destructuring several parts of `context` such as `print`, `filesystem`, etc. Those get used in the main body of the function to perform the various tasks. + +#### Extensions + +Any file exports in this directory will get automatically added to the `context` object as additional properties. Let's say we wanted a `context.foo()` function. Just add `foo.js` into `./src/extensions` and export a function from there. You'll then be able to access it anywhere as `context.foo()`. + +Notice that there are several functions under the `ignite` extension. For example, `context.ignite.addModule()` is in `./src/extensions/ignite/addModule.js`. + +#### Tests + +`ignite-cli` tests are fairly straightforward. For any new commands or extensions you might add, we recommend adding tests for them here. + +## ignite-dev-screens + +This is an [Ignite plugin](./creating-plugins.md) that adds Ignite development screens to your new app (if you choose to). It runs the `./src/plugin.js` file and copies over the files in `./src/templates` to your project. To edit the generated screens, just edit the files in the templates folder. + +## Documentation and Github + +Github-specific templates and docs are in `./.github`. Other + +## CI Tests + +In the `./bin` folder, you'll find a few helpful scripts that we run before releasing a new version of Ignite. + +_That's it! If you have questions about the structure of Ignite, feel free to open an issue or [join the Infinite Red Community Slack](http://community.infinite.red)._ diff --git a/docs/advanced-guides/using-development-build.md b/docs/advanced-guides/using-development-build.md index 7d240b9d5..42788485f 100644 --- a/docs/advanced-guides/using-development-build.md +++ b/docs/advanced-guides/using-development-build.md @@ -21,14 +21,11 @@ If you're on a Mac, you can use one of these techniques: First, if you already have a copy of Ignite installed with `npm`, uninstall it with the commands listed below. -For Ignite 2.0 and above: (exact one depends on what you may have installed previously) +Exact one depends on what you may have installed previously: + ```sh npm rm -g ignite npm rm -g ignite-cli -``` - -For Ignite 1.x: -```sh npm rm -g react-native-ignite ``` @@ -43,7 +40,7 @@ git@github.com:infinitered/ignite.git cd ignite ``` -Now install use `npm` to install and bootstrap Ignite: +Now use `npm` to install and bootstrap Ignite: ```sh npm install @@ -57,35 +54,22 @@ cd packages/ignite-cli npm link ``` -When we launch, this will be replaced with `npm install -g ignite-cli`. - ->Note: If you get an error at this point, it is probably related to not removing a previously installed version of Ignite. See the commands above to uninstall Ignite. +> Note: If you get an error at this point, it is probably related to not removing a previously installed version of Ignite. See the commands above to uninstall Ignite. #### Setup Overrides -We're not quite ready to push everything up to NPM yet. We're a few days away from this. - -So in the meantime, we have to trick Ignite into installing from our hard drive instead of from npmjs.com. - -We can do this by setting an environment variable. +Now set up an environment variable so Ignite knows where to find its own plugins. Make sure you're in the main `ignite` folder first -- you may have to run `cd ../..`. ```sh -cd .. -echo "export IGNITE_PLUGIN_PATH=$(pwd)" +export IGNITE_PLUGIN_PATH=$(pwd) ``` -^ then copy the output of that into your `.bashrc` or `.zshrc` or just run it in place if you're kicking tires. For example, on my computer, I can do this: + +If you want to add this to your local `.bashrc` or `.zshrc` so it's available on every terminal session, just do this: ```sh -export IGNITE_PLUGIN_PATH=~/src/ir/ignite/packages -ignite new MyIgniteProject --max +echo "export IGNITE_PLUGIN_PATH=$(pwd)" >> ~/.zshrc ``` -> Once we ship to `npm` we can remove this step. When we type `ignite add vector-icons` it will install from npm. But in the meantime, this offers a way to write your own plugins. - - ->If you cannot resolve your issue, the Infinite Red Community Slack may be able to help. You can find us by visiting [http://community.infinite.red](http://community.infinite.red) and then joining the `#ignite` channel. - - ## Testing Your Installation To test your installation of Ignite, let's try generating a new project. Navigate to a new directory where you'd like to create a new project and run the `ignite new` command: @@ -95,7 +79,7 @@ cd ~ ignite new MyApp ``` ->Again, if you are having issues, the Infinite Red Community Slack may be able to help. You can find us by visiting [http://community.infinite.red](http://community.infinite.red) and then joining the `#ignite` channel. +> Again, if you are having issues, the Infinite Red Community Slack may be able to help. You can find us by visiting [http://community.infinite.red](http://community.infinite.red) and then joining the `#ignite` channel.