From 6f564713624a1febdec9176324507fc07a9afd5a Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 27 May 2022 10:33:09 +0100 Subject: [PATCH] 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 --- README.md | 66 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 37 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 8972f82ef4..7093c993e2 100644 --- a/README.md +++ b/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 -================== +------------------ [![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. @@ -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.