Add developer docs
This patch adds developer documentation in the docs/ directory. The documentation is written using sphinx. We also include an npm command to build the documentation (ie npm run docs). Closes-bug: 1651106 Change-Id: Ifcce40e1727ddb5eb7cac8586cb41d6f2a3e78d0
This commit is contained in:
Honza Pokorny
parent
f3bd97eeeb
commit
ae46a1507d
|
|
@ -12,3 +12,4 @@ app.conf
|
|||
messages.pot
|
||||
i18n/extracted-messages*
|
||||
npm-debug.log
|
||||
docs/_build
|
||||
|
|
|
|||
199
README.md
199
README.md
|
|
@ -3,201 +3,34 @@ Team and repository tags
|
|||
|
||||
[](http://governance.openstack.org/reference/tags/index.html)
|
||||
|
||||
<!-- Change things from this point on -->
|
||||
TripleO UI
|
||||
==========
|
||||
|
||||
# Development environment setup
|
||||
## Installation
|
||||
|
||||
Ideally, you should have one powerful machine ("virt host") on which you will install TripleO (the backend). For the development work on the TripleO UI, we recommend installing and configuring the UI directly on your workstation ("local machine") and then pointing it to the machine hosting the TripleO installation.
|
||||
See [installation](docs/installation.rst)
|
||||
|
||||
## Install TripleO
|
||||
## Overview
|
||||
|
||||
Do these steps on the virt host.
|
||||
See [overview](docs/overview.rst)
|
||||
|
||||
Follow the official docs to install and configure TripleO (follow the step up to and including the Undercloud installation):
|
||||
http://docs.openstack.org/developer/tripleo-docs/index.html
|
||||
## Testing
|
||||
|
||||
Once the undercloud is installed, you will need to create a tunnel on your virt host, to make the services running on undercloud available to the UI. The tunnel has the following format:
|
||||
See [testing](docs/testing.rst)
|
||||
|
||||
```
|
||||
ssh -N root@<undercloud_ip> \
|
||||
-L 0.0.0.0:<service_port>:<service_ip>:<service_port>
|
||||
# Repeat the last line for each service.
|
||||
```
|
||||
## Translation
|
||||
|
||||
If you installed the UI with SSL the `service_ip` is the value of `undercloud_public_ip` in undercloud.conf.
|
||||
The ports needed are: 13385, 13000, 13004, 13808, 9000, 13989 and 443.
|
||||
See [translation](docs/translation.rst)
|
||||
|
||||
If you installed the UI **without** SSL the `service_ip` is the value of `network_gateway` in undercloud.conf
|
||||
The ports needed are: 6385, 5000, 8004, 8080, 9000, 8989 and 3000.
|
||||
## Packaging
|
||||
|
||||
Example (with SSL enabled):
|
||||
See [packaging](docs/packaging.rst)
|
||||
|
||||
```
|
||||
ssh -N root@192.168.122.205 \
|
||||
-L 0.0.0.0:13385:192.0.2.2:13385 \
|
||||
-L 0.0.0.0:13000:192.0.2.2:13000 \
|
||||
-L 0.0.0.0:13004:192.0.2.2:13004 \
|
||||
-L 0.0.0.0:13808:192.0.2.2:13808 \
|
||||
-L 0.0.0.0:9000:192.0.2.2:9000 \
|
||||
-L 0.0.0.0:13989:192.0.2.2:13989 \
|
||||
-L 0.0.0.0:443:192.0.2.2:443
|
||||
```
|
||||
## Contributing
|
||||
|
||||
Example (without SSL):
|
||||
See [contributing](docs/contributing.rst)
|
||||
|
||||
```
|
||||
ssh -N root@192.168.122.205 \
|
||||
-L 0.0.0.0:6385:192.0.2.1:6385 \
|
||||
-L 0.0.0.0:5000:192.0.2.1:5000 \
|
||||
-L 0.0.0.0:8004:192.0.2.1:8004 \
|
||||
-L 0.0.0.0:8080:192.0.2.1:8080 \
|
||||
-L 0.0.0.0:9000:192.0.2.1:9000 \
|
||||
-L 0.0.0.0:8989:192.0.2.1:8989 \
|
||||
-L 0.0.0.0:3000:192.0.2.1:3000
|
||||
```
|
||||
|
||||
### Install Validations
|
||||
## License
|
||||
|
||||
To install Validations as part of your undercloud, make sure `enable_validations` is set to `true` in `undercloud.conf`, prior to running `openstack undercloud install`.
|
||||
|
||||
## Install TripleO UI
|
||||
|
||||
Do these steps on the local machine.
|
||||
|
||||
Install nodejs and npm:
|
||||
```
|
||||
sudo dnf install nodejs
|
||||
```
|
||||
|
||||
To compile and install native addons from npm you may also need to install build tools:
|
||||
```
|
||||
sudo dnf install gcc-c++ make
|
||||
```
|
||||
|
||||
Clone the TripleO UI repo, change into the newly clone directory, install the dependencies and start the development server:
|
||||
```
|
||||
git clone https://github.com/openstack/tripleo-ui.git
|
||||
cd tripleo-ui
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
Optionally start Karma to run tests after every change:
|
||||
```
|
||||
npm run test:watch
|
||||
```
|
||||
|
||||
Copy `dist/tripleo_ui_config.js.sample` to `dist/tripleo_ui_config.js`, uncomment the lines pertaining to OpenStack services (`keystone`, `tripleo`, etc), and add the urls where these services can be accessed (in this case, the IP address of the virt host). You can set values for the other services as well to override the values coming from the keystone serviceCatalog.
|
||||
|
||||
To access the UI, navigate to `http://localhost:3000/`
|
||||
|
||||
## Troubleshooting installation
|
||||
|
||||
In case of problems with the nodejs installation, refer to https://nodejs.org/en/download/package-manager/#enterprise-linux-and-fedora.
|
||||
|
||||
In case of errors during `npm install`, remove `node_modules` directory and clean npm cache, then run `npm install` again:
|
||||
```
|
||||
rm node_modules
|
||||
npm cache clean
|
||||
npm install
|
||||
```
|
||||
|
||||
|
||||
# Contributing
|
||||
|
||||
Use OpenStack Gerrit for patches and reviews (http://docs.openstack.org/infra/manual/developers.html).
|
||||
|
||||
1. `git clone https://github.com/openstack/tripleo-ui.git` (if you didn't already)
|
||||
2. Install git-review: `sudo dnf install git-review`
|
||||
3. Setup Gerrit: `git review -s`
|
||||
4. Develop on feature-branch locally
|
||||
5. Run `git review` to push patch for review.
|
||||
6. Review and merge patches on OpenStack Gerrit: https://review.openstack.org/#/q/project:openstack/tripleo-ui
|
||||
|
||||
|
||||
# Tests
|
||||
|
||||
## Single test run
|
||||
|
||||
- `npm test` (alternatively run `karma start --single-run`)
|
||||
- `npm run lint` to run ESLint
|
||||
|
||||
Info on Linting setup: https://medium.com/@dan_abramov/lint-like-it-s-2015-6987d44c5b48
|
||||
.eslintrc rules tweaks: http://blog.javascripting.com/2015/09/07/fine-tuning-airbnbs-eslint-config/
|
||||
|
||||
## Tests during development
|
||||
|
||||
Start Karma to run tests after every change ```npm run test:watch```
|
||||
|
||||
## Debugging tests
|
||||
|
||||
1. option:
|
||||
- use `console.log` in the test and see the output in karma server output
|
||||
2. option:
|
||||
- install karma-chrome-launcher npm module `npm install karma-chrome-launcher --save-dev`
|
||||
- replace/add 'Chrome' to browsers in `karma.conf.js`
|
||||
- now Karma will launch Chrome to run the tests
|
||||
- use `debugger;` statement in test code to add breakpoints
|
||||
- in Karma Chrome window click 'debug' button and debug in chrome developer tools as usual
|
||||
- optionally you can use karma-jasmine-html-reporter for better test output (https://www.npmjs.com/package/karma-jasmine-html-reporter)
|
||||
- make sure you don't push those changes to `karma.conf.js` and `package.json` as part of your patch
|
||||
|
||||
|
||||
# Style guide and conventions
|
||||
|
||||
Style guide: https://github.com/airbnb/javascript
|
||||
|
||||
Multiple words in folder names should be separated by an underscore:
|
||||
|
||||
```
|
||||
src/js/components/environment_configuration
|
||||
```
|
||||
|
||||
|
||||
# Documentation
|
||||
|
||||
Use JSDoc docstrings in code to provide source for autogenerated documentation (http://usejsdoc.org/).
|
||||
|
||||
|
||||
# Translation
|
||||
|
||||
tripleo-ui uses the react-intl package for translation.
|
||||
|
||||
|
||||
## Adding translateable strings
|
||||
|
||||
Strings are prepared for translation using react-intl's `defineMessages` API. Check out `./src/js/components/deployment_plan/` for examples.
|
||||
|
||||
|
||||
## Extracting messages from components
|
||||
|
||||
Messages are extracted during the build process (`npm run build`) and stored in the `./i18n/extracted-messages/` folder. These files can be converted into a single `.pot` file with this command:
|
||||
|
||||
```
|
||||
npm run json2pot
|
||||
```
|
||||
|
||||
The resulting file (`./messages.pot`) can be uploaded to http://zanata.org to create/update the translation.
|
||||
|
||||
|
||||
## Using translated `.po` files
|
||||
|
||||
The translated language file (`messages.po`) then needs to be converted into one JSON file per language (Japanese in this example):
|
||||
|
||||
```
|
||||
npm run po2json -- messages.po -o ./i18n/locales/ja.json
|
||||
```
|
||||
|
||||
|
||||
## Adding a new language
|
||||
|
||||
The languages are defined in the ./src/js/components/i18n/I18NProvider component. To add another language, import the relevant locale data from the react-intl packages, as well as the JSON containing the translation and add the new language to the MESSAGES constant:
|
||||
|
||||
```
|
||||
import ja from 'react-intl/locale-data/ja';
|
||||
import jaMessages from '../../../../i18n/locales/ja.json';
|
||||
|
||||
const MESSAGES = {
|
||||
ja: jaMessages.messages
|
||||
};
|
||||
```
|
||||
Apache 2.0, see LICENSE for details.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,20 @@
|
|||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXPROJ = tripleo-ui
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
# implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
extensions = ['oslosphinx']
|
||||
|
||||
source_suffix = '.rst'
|
||||
|
||||
master_doc = 'index'
|
||||
|
||||
project = u'tripleo-ui'
|
||||
copyright = u'2017, OpenStack Foundation'
|
||||
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
htmlhelp_basename = '%sdoc' % project
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
Contributing
|
||||
============
|
||||
|
||||
Use `OpenStack Gerrit`_ for patches and reviews.
|
||||
|
||||
1. ``git clone https://github.com/openstack/tripleo-ui.git``
|
||||
2. Install git-review: ``sudo dnf install git-review``
|
||||
3. Setup Gerrit: ``git review -s``
|
||||
4. Develop on a feature branch locally
|
||||
5. Run ``git review`` to push your patch up for review
|
||||
6. `Review and merge patches`_ on OpenStack Gerrit
|
||||
|
||||
.. _OpenStack Gerrit: http://docs.openstack.org/infra/manual/developers.html
|
||||
.. _Review and merge patches: https://review.openstack.org/#/q/project:openstack/tripleo-ui
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
.. tripleo-ui documentation master file, created by
|
||||
sphinx-quickstart on Tue Jan 24 10:31:02 2017.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Welcome to Tripleo UI's developer documentation!
|
||||
================================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
installation
|
||||
overview
|
||||
testing
|
||||
translation
|
||||
packaging
|
||||
contributing
|
||||
|
||||
* `Source code`_
|
||||
* `Bugs`_
|
||||
|
||||
.. _Source code: https://github.com/openstack/tripleo-ui
|
||||
.. _Bugs: https://bugs.launchpad.net/tripleo/+bugs?field.tag=ui
|
||||
|
|
@ -0,0 +1,129 @@
|
|||
Installation
|
||||
============
|
||||
|
||||
Development environment setup
|
||||
-----------------------------
|
||||
|
||||
Ideally, you should have one powerful machine ("virt host") on which you will
|
||||
install TripleO (the backend). For the development work on the TripleO UI, we
|
||||
recommend installing and configuring the UI directly on your workstation ("local
|
||||
machine") and then pointing it to the machine hosting the TripleO installation.
|
||||
|
||||
Install TripleO
|
||||
---------------
|
||||
|
||||
Do these steps on the virt host.
|
||||
|
||||
Follow the `official docs`_ to install and configure TripleO (follow the step up to
|
||||
and including the Undercloud installation).
|
||||
|
||||
.. _official docs: http://docs.openstack.org/developer/tripleo-docs/index.html
|
||||
|
||||
Once the undercloud is installed, you will need to create a tunnel on your virt
|
||||
host, to make the services running on undercloud available to the UI. The tunnel
|
||||
has the following format:
|
||||
|
||||
::
|
||||
|
||||
ssh -N root@<undercloud_ip> \
|
||||
-L 0.0.0.0:<service_port>:<service_ip>:<service_port>
|
||||
# Repeat the last line for each service.
|
||||
|
||||
If you installed the UI with SSL the ``service_ip`` is the value of
|
||||
``undercloud_public_ip`` in undercloud.conf. The ports needed are: 13385,
|
||||
13000, 13004, 13808, 9000, 13989 and 443.
|
||||
|
||||
If you installed the UI **without** SSL, the ``service_ip`` is the value of
|
||||
``network_gateway`` in undercloud.conf. The ports needed are: 6385, 5000, 8004,
|
||||
8080, 9000, 8989 and 3000.
|
||||
|
||||
Example (with SSL enabled):
|
||||
|
||||
::
|
||||
|
||||
ssh -N root@192.168.122.205 \
|
||||
-L 0.0.0.0:13385:192.0.2.2:13385 \
|
||||
-L 0.0.0.0:13000:192.0.2.2:13000 \
|
||||
-L 0.0.0.0:13004:192.0.2.2:13004 \
|
||||
-L 0.0.0.0:13808:192.0.2.2:13808 \
|
||||
-L 0.0.0.0:9000:192.0.2.2:9000 \
|
||||
-L 0.0.0.0:13989:192.0.2.2:13989 \
|
||||
-L 0.0.0.0:443:192.0.2.2:443
|
||||
|
||||
Example (without SSL):
|
||||
|
||||
::
|
||||
|
||||
ssh -N root@192.168.122.205 \
|
||||
-L 0.0.0.0:6385:192.0.2.1:6385 \
|
||||
-L 0.0.0.0:5000:192.0.2.1:5000 \
|
||||
-L 0.0.0.0:8004:192.0.2.1:8004 \
|
||||
-L 0.0.0.0:8080:192.0.2.1:8080 \
|
||||
-L 0.0.0.0:9000:192.0.2.1:9000 \
|
||||
-L 0.0.0.0:8989:192.0.2.1:8989 \
|
||||
-L 0.0.0.0:3000:192.0.2.1:3000
|
||||
|
||||
Install Validations
|
||||
-------------------
|
||||
|
||||
To install Validations as part of your undercloud, make sure
|
||||
``enable_validations`` is set to ``true`` in ``undercloud.conf``, prior to
|
||||
running ``openstack undercloud install``.
|
||||
|
||||
Install TripleO UI
|
||||
------------------
|
||||
|
||||
Do these steps on the local machine.
|
||||
|
||||
Install nodejs and npm:
|
||||
|
||||
::
|
||||
|
||||
sudo dnf install nodejs
|
||||
|
||||
To compile and install native addons from npm you may also need to install build
|
||||
tools:
|
||||
|
||||
::
|
||||
|
||||
sudo dnf install gcc-c++ make
|
||||
|
||||
Clone the TripleO UI repo, change into the newly clone directory, install the
|
||||
dependencies and start the development server:
|
||||
|
||||
::
|
||||
|
||||
git clone https://github.com/openstack/tripleo-ui.git
|
||||
cd tripleo-ui
|
||||
npm install
|
||||
npm start
|
||||
|
||||
Optionally start Karma to run tests after every change:
|
||||
|
||||
::
|
||||
|
||||
npm run test:watch
|
||||
|
||||
Copy ``dist/tripleo_ui_config.js.sample`` to ``dist/tripleo_ui_config.js``,
|
||||
uncomment the lines pertaining to OpenStack services (``keystone``, ``tripleo``,
|
||||
etc), and add the urls where these services can be accessed (in this case, the
|
||||
IP address of the virt host). You can set values for the other services as well
|
||||
to override the values coming from the keystone serviceCatalog.
|
||||
|
||||
To access the UI, navigate to ``http://localhost:3000/``
|
||||
|
||||
Troubleshooting installation
|
||||
----------------------------
|
||||
|
||||
In case of problems with the nodejs installation, refer to this `guide`_.
|
||||
|
||||
.. _guide: https://nodejs.org/en/download/package-manager/#enterprise-linux-and-fedora
|
||||
|
||||
In case of errors during ``npm install``, remove ``node_modules`` directory and
|
||||
clean npm cache, then run ``npm install`` again:
|
||||
|
||||
::
|
||||
|
||||
rm -rf node_modules
|
||||
npm cache clean
|
||||
npm install
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
Overview
|
||||
========
|
||||
|
||||
There are four major tools that we use to develop the TripleO UI:
|
||||
|
||||
* React
|
||||
* Redux
|
||||
* Babel
|
||||
* Webpack
|
||||
|
||||
React
|
||||
-----
|
||||
|
||||
React is the presentation layer.
|
||||
|
||||
https://github.com/facebook/react
|
||||
|
||||
Redux
|
||||
-----
|
||||
|
||||
Redux is the data layer. It's responsible for managing the state of the
|
||||
application. If you want to change a piece of data in the application, you need
|
||||
to go through Redux. Most of the Redux code is contained in Action and Reducer
|
||||
files.
|
||||
|
||||
https://github.com/reactjs/redux
|
||||
|
||||
Babel
|
||||
-----
|
||||
|
||||
Babel is a translation layer that allows us to write code using recent
|
||||
Javascript features without having to worry about browser compatibility. We can
|
||||
write code in es6, and Babel will compile this to standard Javascript.
|
||||
|
||||
https://github.com/babel/babel
|
||||
|
||||
Webpack
|
||||
-------
|
||||
|
||||
Webpack is our build tool. Webpack uses Babel to actually produce a minified
|
||||
Javascript file that can be used in production. Webpack gives us a development
|
||||
server which watches for file changes, and automatically recompiles our code.
|
||||
|
||||
https://github.com/webpack/webpack
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
TripleO UI packaging
|
||||
====================
|
||||
|
||||
TL;DR
|
||||
-----
|
||||
|
||||
* We need people from the RDO team to approve all changes
|
||||
* New packages are built on every upstream merge commit
|
||||
* Use npm shrinkwrap when updating dependencies in ``package.json``
|
||||
|
||||
Upstream
|
||||
--------
|
||||
|
||||
For upstream releases, we only provide a source tarball. This is released via
|
||||
the ``project-config`` machinery just like other TripleO projects. The tarball is
|
||||
produced by running ``npm pack`` in the root of the project, and excludes the
|
||||
``node_modules`` directory. The tarballs are available `here`_.
|
||||
|
||||
RDO
|
||||
---
|
||||
|
||||
The upstream TripleO CI relies on packages provided by the `RDO project`_.
|
||||
Therefore, it's important to keep the RDO packages up-to-date, and to prevent
|
||||
the builds from failing.
|
||||
|
||||
The product of RDO packaging is a set of two RPMs:
|
||||
|
||||
* `openstack-tripleo-ui-deps`_
|
||||
* `openstack-tripleo-ui`_
|
||||
|
||||
And of course, the second one depends on the first one. The `-deps` package
|
||||
contains the contents of the `node_modules` directory.
|
||||
|
||||
An RPM is created from a `.spec` file. These files can be access via the above
|
||||
GitHub links. Any changes to the files are subject to review by the RDO team.
|
||||
This can be a lengthy process because software licenses need to be reviewed.
|
||||
|
||||
RDO builds packages in two different streams: trunk and stable. Study the
|
||||
following graphic to understand how code flows through the pipeline:
|
||||
|
||||
.. image:: https://www.rdoproject.org/images/documentation/rdo-full-workflow-high-level-no-buildlogs.png
|
||||
:alt: RDO diagram
|
||||
|
||||
What to do when dependencies change
|
||||
-----------------------------------
|
||||
|
||||
This applies both to adding *new* dependencies, and upgrading *existing* ones.
|
||||
|
||||
1. Make the required changes in ``package.json``
|
||||
2. ``$ rm -rf node_modules``
|
||||
3. ``$ npm cache clean``
|
||||
4. ``$ npm install``
|
||||
5. ``$ npm shrinkwrap``
|
||||
6. Commit those changes along with your dependency changes in ``tripleo-ui``.
|
||||
Your patch should only include the necessary changes to update the
|
||||
dependency. Submit another patch for your feature/bugfix. In the
|
||||
commit message, add a link to the dependency (GitHub or similar), and
|
||||
indicate the project's license. We use the "workflow" field on this
|
||||
patch to indicate whether a packager has reviewed the changes: "-1" means
|
||||
this has not happened, or there are issues with the new dependency; "+1"
|
||||
means it's been reviewed, and the change is approved.
|
||||
7. Update the `openstack-tripleo-ui-deps`_ package. Currently, this is done by
|
||||
submitting a pull request on GitHub. There are plans in place to move the
|
||||
workflow for this repository to the gerrit system.
|
||||
8. Update the `openstack-tripleo-ui`_ spec so that it points to the new version
|
||||
of `openstack-tripleo-ui-deps`_. This is done by submitting a patch via
|
||||
`gerrit`_.
|
||||
|
||||
.. _here: http://tarballs.openstack.org/tripleo-ui/
|
||||
.. _openstack-tripleo-ui-deps: https://github.com/rdo-common/openstack-tripleo-ui-deps
|
||||
.. _openstack-tripleo-ui: https://github.com/rdo-packages/tripleo-ui-distgit/tree/rpm-master
|
||||
.. _RDO project: https://www.rdoproject.org
|
||||
.. _gerrit: https://review.rdoproject.org
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
Testing
|
||||
=======
|
||||
|
||||
Single test run
|
||||
---------------
|
||||
|
||||
- ``npm test`` (alternatively run ``karma start --single-run``)
|
||||
- ``npm run lint`` to run ESLint
|
||||
|
||||
`Info on linting setup`_ and `.eslintrc rules tweaks`_.
|
||||
|
||||
.. _Info on linting setup: https://medium.com/@dan_abramov/lint-like-it-s-2015-6987d44c5b48
|
||||
.. _.eslintrc rules tweaks: http://blog.javascripting.com/2015/09/07/fine-tuning-airbnbs-eslint-config/
|
||||
|
||||
Tests during development
|
||||
------------------------
|
||||
|
||||
Start Karma to run tests after every change ``npm run test:watch``.
|
||||
|
||||
Debugging tests
|
||||
---------------
|
||||
|
||||
1. option
|
||||
|
||||
- use ``console.log`` in the test and see the output in karma server output
|
||||
|
||||
2. option
|
||||
|
||||
- install karma-chrome-launcher npm module
|
||||
``npm install karma-chrome-launcher --save-dev``
|
||||
- replace/add 'Chrome' to browsers in ``karma.conf.js``
|
||||
- now Karma will launch Chrome to run the tests
|
||||
- use ``debugger;`` statement in test code to add breakpoints
|
||||
- in Karma Chrome window click 'debug' button and debug in chrome developer
|
||||
tools as usual
|
||||
- optionally you can use `karma-jasmine-html-reporter`_ for better test output
|
||||
- make sure you don't push those changes to ``karma.conf.js`` and
|
||||
``package.json`` as part of your patch
|
||||
|
||||
.. _karma-jasmine-html-reporter: https://www.npmjs.com/package/karma-jasmine-html-reporter
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
Translation
|
||||
===========
|
||||
|
||||
Tripleo UI uses the react-intl package for translation.
|
||||
|
||||
Adding translateable strings
|
||||
----------------------------
|
||||
|
||||
Strings are prepared for translation using react-intl's ``defineMessages``
|
||||
API. Check out ``./src/js/components/deployment_plan/`` for examples.
|
||||
|
||||
Extracting messages from components
|
||||
-----------------------------------
|
||||
|
||||
Messages are extracted during the build process (``npm run build``) and stored
|
||||
in the ``./i18n/extracted-messages/`` folder. These files can be converted into
|
||||
a single ``.pot`` file with this command:
|
||||
|
||||
::
|
||||
|
||||
npm run json2pot
|
||||
|
||||
The resulting file (``./messages.pot``) can be uploaded to `Zanata`_ to
|
||||
create/update the translation.
|
||||
|
||||
.. _Zanata: http://zanata.org
|
||||
|
||||
Using translated ``.po`` files
|
||||
------------------------------
|
||||
|
||||
The translated language file (``messages.po``) then needs to be converted into
|
||||
one JSON file per language (Japanese in this example):
|
||||
|
||||
::
|
||||
|
||||
npm run po2json -- messages.po -o ./i18n/locales/ja.json
|
||||
|
||||
|
||||
Adding a new language
|
||||
---------------------
|
||||
|
||||
The languages are defined in the ``./src/js/components/i18n/I18NProvider``
|
||||
component. To add another language, import the relevant locale data from the
|
||||
react-intl packages, as well as the JSON containing the translation and add the
|
||||
new language to the MESSAGES constant:
|
||||
|
||||
.. code-block:: js
|
||||
|
||||
import ja from 'react-intl/locale-data/ja';
|
||||
import jaMessages from '../../../../i18n/locales/ja.json';
|
||||
|
||||
const MESSAGES = {
|
||||
ja: jaMessages.messages
|
||||
};
|
||||
|
|
@ -74,7 +74,8 @@
|
|||
"test": "karma start --single-run",
|
||||
"test:watch": "karma start",
|
||||
"json2pot": "rip json2pot ./i18n/extracted-messages/**/*.json -o ./i18n/messages.pot",
|
||||
"po2json": "rip po2json -m ./i18n/extracted-messages/**/*.json"
|
||||
"po2json": "rip po2json -m ./i18n/extracted-messages/**/*.json",
|
||||
"docs": "cd docs && make html && cd -"
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
|
|
|
|||
Loading…
Reference in New Issue