```code _ _ _ _ __ _ _ _(_)____ _ __ ___ __ _ ___| |_ ___ __| | | __ / _` | | | | |_ / | '__/ _ \/ _` |/ __| __| / __|/ _` | |/ / | (_| | |_| | |/ / | | | __/ (_| | (__| |_ \__ \ (_| | < \__, |\__,_|_/___| |_| \___|\__,_|\___|\__| |___/\__,_|_|\_\ |_| ``` The Quiz React SDK is a collection of React components and tools for building applications built on top of the Instructure Quiz API service. ## Getting Started First, install all of the Docker prerequisites (VirtualBox, Docker, Dinghy/Dory): - https://github.com/instructure/canvas-lms/blob/stable/doc/docker/getting_docker.md Now you're ready to spin up the SDK docs application for development: ```sh bin/dev-setup docker-compose up -d web open http://quiz.docker ``` ## Using Local Development Quiz API The default development environment for the SDK uses a prebuilt docker image of the Quiz API service. While working on the SDK, you will likely find that it's necessary to hook it up with a local development version of the service. In your `quiz_api` repository, edit your `docker-compose.override.yml` to enable integration seeds. It should look something like this: ```yml # For SDK integration tests: - ../quiz_web/integration:/usr/src/app/demo ``` Now run the integration seeds in your `quiz_api` environment: ```sh bin/seed-sdk-data.sh ``` The api's sdk seeding creates a json config file that is uploaded to S3. In order to consume the config data quiz_web needs access to this url. Back in your `quiz_web` checkout, enable the `CONFIG_URL` setting in your `docker-compose.override.yml` for the `web` and `integration` containers, by uncommenting the following line in both locations: ```yml CONFIG_URL: http://quiz.s3.docker/dev_uploads/sdk-demo/(development|test).config.json ``` Now restart your web (and integration) container(s) if they are already running: ```sh docker-compose restart web integration ``` If you are developing quiz_web without docker, add the url to env: ```sh export CONFIG_URL=http://quiz.s3.docker/dev_uploads/sdk-demo/development.config.json ``` and start thes server and go to localhost:8080 ```sh yarn run start ``` ## Running without Docker While it's highly recommended you install and use Docker to work on the SDK, there are a couple things that are more difficult to do within Docker, and you may want to run the webpack-dev-server for the docs app outside of Docker. This is often desired for better support of filesystem watchers, and for linking development checkouts of NPM package dependencies. Currently, the following versions of Node and Yarn are required: - [Node]: 7.5.0 or later - [Yarn]: 0.27.5 or later [Node]: https://nodejs.org/ [Yarn]: https://yarnpkg.com/lang/en/docs/install/ With Node and Yarn installed, spin up webpack-dev-server locally by running: ```sh yarn start ``` You can access the docs application at: http://localhost:8080 ## Staying Updated Anytime your pull the latest changes to the SDK, you must also download the latest NPM packages, and rebuild your docker images. This can be done like so: ```sh git pull bin/dev-update ``` If a standard `dev-update` is still giving you trouble, run `bin/table-flip` to clear out some npm junk that might be getting in the way. It won't clear out any of your data since we're just dealing with quiz_web here, so it's safe to run without worrying too much about side effects. ## Testing with local quiz-interactions To override the quiz-interactions node module with a local copy, uncomment the following line in your `docker.compose.override.yml`, making sure the path actually points to where you have the quiz_interactions project on your machine. ```sh - ../quiz_interactions/__build__:/usr/src/app/node_modules/quiz-interactions ``` In order for there to actually be something in `quiz_interactions/__build__` (which is what actually gets pulled in), you'll need to run either `yarn build` or `yarn build:watch` in the quiz_interactions project. After making those changes, you will need to restart the web container in order for it to pick up the changes to the `docker.compose.override.yml`. ## Contributing ### Commit Messages We have some special tooling in place around commit messages. Please see the [committing docs](doc/committing.md) for more details. ### Code Formatting We are using [EditorConfig] to help with code formatting. You should enable support for EditorConfig in your favorite code editor. [EditorConfig]: http://editorconfig.org/ ### Linting Run `yarn run lint` to lint the src dir. We are using [ESLint](http://eslint.org/). You might want to install this git pre-push hook to automatically lint changes: ```sh cp hooks/pre-push.example .git/hooks/pre-push ``` You might need to globally install a few eslint packages, depending on your environment. Here's a start: ```sh yarn global add eslint babel-eslint eslint-config-standard{,-react} \ eslint-plugin-{format-message,react,mocha,standard,promise} ``` ### Internationalization Any string that needs I18n will use formatMessage so that yarn can extract those strings. If you have added any strings that you expect to be internationalized to the project, be sure to run `docker-compose run —rm web yarn run extract` to have yarn extract the I18n strings. ### Sublime Setup If you use Sublime Text for your code editor, we recommend the following: 1. Install the following plugins: - https://github.com/sindresorhus/editorconfig-sublime - http://sublimelinter.readthedocs.org/en/latest/ - https://github.com/roadhump/SublimeLinter-eslint 3. Install NPM packages locally outside of Docker: `yarn install` 4. Restart Sublime Text ### Styles The app uses css modules with postcss. 'styles/variables.js' defined variables which are automatically added to css files using the postcss-simple-vars loader. If you add/change a variable, in order to see the change you'll need to rerun webpack and restart the dev server. ## Publishing a New Release With an account that has the correct permissions on npmjs, run the following: 1. `npm login` 2. Provide account details 3. `npm publish` Verify you are running the prepublish script inside the docker container to ensure you are using the correct version of Node.