Make README markdown more consistent (#8705)
* Make README markdown more consistent * Most lines were 80 characters wide, others not - make them all 80. * Switch to === titles in README where possible
This commit is contained in:
Andy Balaam
GitHub
parent
aef080ac80
commit
6f56471362
1 changed files with 37 additions and 29 deletions
66
README.md
66
README.md
|
|
@ -22,17 +22,18 @@ a 'skin'. A skin provides:
|
|||
* The containing application
|
||||
* Zero or more 'modules' containing non-UI functionality
|
||||
|
||||
As of Aug 2018, the only skin that exists is [`vector-im/element-web`](https://github.com/vector-im/element-web/); it and
|
||||
As of Aug 2018, the only skin that exists is
|
||||
[`vector-im/element-web`](https://github.com/vector-im/element-web/); it and
|
||||
`matrix-org/matrix-react-sdk` should effectively
|
||||
be considered as a single project (for instance, matrix-react-sdk bugs
|
||||
are currently filed against vector-im/element-web rather than this project).
|
||||
|
||||
Translation Status
|
||||
==================
|
||||
------------------
|
||||
[](https://translate.element.io/engage/element-web/?utm_source=widget)
|
||||
|
||||
Developer Guide
|
||||
===============
|
||||
---------------
|
||||
|
||||
Platform Targets:
|
||||
* Chrome, Firefox and Safari.
|
||||
|
|
@ -51,21 +52,25 @@ Please follow the Matrix JS/React code style as per:
|
|||
https://github.com/matrix-org/matrix-react-sdk/blob/master/code_style.md
|
||||
|
||||
Code should be committed as follows:
|
||||
* All new components: https://github.com/matrix-org/matrix-react-sdk/tree/master/src/components
|
||||
* Element-specific components: https://github.com/vector-im/element-web/tree/master/src/components
|
||||
* In practice, `matrix-react-sdk` is still evolving so fast that the maintenance
|
||||
burden of customising and overriding these components for Element can seriously
|
||||
impede development. So right now, there should be very few (if any) customisations for Element.
|
||||
* All new components:
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/src/components
|
||||
* Element-specific components:
|
||||
https://github.com/vector-im/element-web/tree/master/src/components
|
||||
* In practice, `matrix-react-sdk` is still evolving so fast that the
|
||||
maintenance burden of customising and overriding these components for
|
||||
Element can seriously impede development. So right now, there should be
|
||||
very few (if any) customisations for Element.
|
||||
* CSS: https://github.com/matrix-org/matrix-react-sdk/tree/master/res/css
|
||||
* Theme specific CSS & resources: https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
|
||||
* Theme specific CSS & resources:
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
|
||||
|
||||
React components in matrix-react-sdk come in two different flavours:
|
||||
'structures' and 'views'. Structures are stateful components which handle the
|
||||
more complicated business logic of the app, delegating their actual presentation
|
||||
rendering to stateless 'view' components. For instance, the RoomView component
|
||||
that orchestrates the act of visualising the contents of a given Matrix chat room
|
||||
tracks lots of state for its child components which it passes into them for visual
|
||||
rendering via props.
|
||||
that orchestrates the act of visualising the contents of a given Matrix chat
|
||||
room tracks lots of state for its child components which it passes into them for
|
||||
visual rendering via props.
|
||||
|
||||
Good separation between the components is maintained by adopting various best
|
||||
practices that anyone working with the SDK needs to be aware of and uphold:
|
||||
|
|
@ -82,18 +87,19 @@ practices that anyone working with the SDK needs to be aware of and uphold:
|
|||
|
||||
* Per-view CSS is optional - it could choose to inherit all its styling from
|
||||
the context of the rest of the app, although this is unusual for any but
|
||||
* Theme specific CSS & resources: https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
|
||||
structural components (lacking presentation logic) and the simplest view
|
||||
components.
|
||||
* Theme specific CSS & resources:
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
|
||||
structural components (lacking presentation logic) and the simplest view
|
||||
components.
|
||||
|
||||
* The view MUST *only* refer to the CSS rules defined in its own CSS file.
|
||||
'Stealing' styling information from other components (including parents)
|
||||
is not cool, as it breaks the independence of the components.
|
||||
|
||||
* CSS classes are named with an app-specific name-spacing prefix to try to avoid
|
||||
CSS collisions. The base skin shipped by Matrix.org with the matrix-react-sdk
|
||||
uses the naming prefix "mx_". A company called Yoyodyne Inc might use a
|
||||
prefix like "yy_" for its app-specific classes.
|
||||
* CSS classes are named with an app-specific name-spacing prefix to try to
|
||||
avoid CSS collisions. The base skin shipped by Matrix.org with the
|
||||
matrix-react-sdk uses the naming prefix "mx_". A company called Yoyodyne
|
||||
Inc might use a prefix like "yy_" for its app-specific classes.
|
||||
|
||||
* CSS classes use upper camel case when they describe React components - e.g.
|
||||
.mx_MessageTile is the selector for the CSS applied to a MessageTile view.
|
||||
|
|
@ -130,13 +136,13 @@ the distinction between 'structural' and 'view' components, so we backed away
|
|||
from it.
|
||||
|
||||
Github Issues
|
||||
=============
|
||||
-------------
|
||||
|
||||
All issues should be filed under https://github.com/vector-im/element-web/issues
|
||||
for now.
|
||||
|
||||
Development
|
||||
===========
|
||||
-----------
|
||||
|
||||
Ensure you have the latest LTS version of Node.js installed.
|
||||
|
||||
|
|
@ -145,9 +151,10 @@ guide](https://classic.yarnpkg.com/docs/install) if you do not have it
|
|||
already. This project has not yet been migrated to Yarn 2, so please ensure
|
||||
`yarn --version` shows a version from the 1.x series.
|
||||
|
||||
`matrix-react-sdk` depends on [`matrix-js-sdk`](https://github.com/matrix-org/matrix-js-sdk). To make use of changes in the
|
||||
latter and to ensure tests run against the develop branch of `matrix-js-sdk`,
|
||||
you should set up `matrix-js-sdk`:
|
||||
`matrix-react-sdk` depends on
|
||||
[`matrix-js-sdk`](https://github.com/matrix-org/matrix-js-sdk). To make use of
|
||||
changes in the latter and to ensure tests run against the develop branch of
|
||||
`matrix-js-sdk`, you should set up `matrix-js-sdk`:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/matrix-org/matrix-js-sdk
|
||||
|
|
@ -170,8 +177,7 @@ yarn install
|
|||
See the [help for `yarn link`](https://classic.yarnpkg.com/docs/cli/link) for
|
||||
more details about this.
|
||||
|
||||
Running tests
|
||||
=============
|
||||
### Running tests
|
||||
|
||||
Ensure you've followed the above development instructions and then:
|
||||
|
||||
|
|
@ -179,7 +185,9 @@ Ensure you've followed the above development instructions and then:
|
|||
yarn test
|
||||
```
|
||||
|
||||
## End-to-End tests
|
||||
### End-to-End tests
|
||||
|
||||
Make sure you've got your Element development server running (by doing `yarn start` in element-web), and then in this project, run `yarn run e2etests`.
|
||||
See [`test/end-to-end-tests/README.md`](https://github.com/matrix-org/matrix-react-sdk/blob/develop/test/end-to-end-tests/README.md) for more information.
|
||||
Make sure you've got your Element development server running (by doing `yarn
|
||||
start` in element-web), and then in this project, run `yarn run e2etests`. See
|
||||
[`test/end-to-end-tests/README.md`](https://github.com/matrix-org/matrix-react-sdk/blob/develop/test/end-to-end-tests/README.md)
|
||||
for more information.
|
||||
|
|
|
|||
Loading…
Reference in a new issue