Skip to content
This repository has been archived by the owner on Sep 11, 2024. It is now read-only.

Commit

Permalink
Make README markdown more consistent (#8705)
Browse files Browse the repository at this point in the history 
* Make README markdown more consistent
* Most lines were 80 characters wide, others not - make them all 80.
* Switch to === titles in README where possible
  • Loading branch information
@andybalaam
andybalaam authored May 27, 2022
1 parent aef080a commit 6f56471
Showing 1 changed file with 37 additions and 29 deletions.
66 changes: 37 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
==================
------------------
[![Translation status](https://translate.element.io/widgets/element-web/-/multi-auto.svg)](https://translate.element.io/engage/element-web/?utm_source=widget)

Developer Guide
===============
---------------

Platform Targets:
* Chrome, Firefox and Safari.
Expand All @@ -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:
Expand All @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -170,16 +177,17 @@ 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:

```bash
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.

0 comments on commit 6f56471

Please sign in to comment.