Development Standards

Upstream InvenioRDM standards

KCWorks is built on top of InvenioRDM, which has a number of standards for coding style and practices. These standards are documented at https://inveniordm.readthedocs.io/en/latest/development/best-practices. KCWorks developers should follow these standards to ensure that code can be contributed back to the wider InvenioRDM project where desirable.

Code Style

Python

Python code should be formatted using the black formatter.

JavaScript

JavaScript code should be formatted using the prettier formatter. Indentation should be 2 spaces.

CSS

CSS code should be formatted using the prettier formatter. Indentation should be 4 spaces.

Accessibility

KCWorks should conform to WCAG 2.1 AA standards for web accessibility as well as to the InvenioRDM accessibility guidelines: https://inveniordm.docs.cern.ch/develop/best-practices/accessibility/.

UI/UX

KCWorks UI elements should adhere to the InvenioRDM UI/UX guidelines: https://inveniordm.docs.cern.ch/develop/best-practices/ui/.

CSS and Theming

KCWorks uses a custom theme layer built on top of the InvenioRDM default theme, which employs the Semantic UI library (https://semantic-ui.com/) and its standard implementation in React (https://react.semantic-ui.com/). Development should follow the InvenioRDM theming guidelines: https://inveniordm.docs.cern.ch/develop/best-practices/theming/.

React components

KCWorks uses React as much as possible for the UI layer, wherever possible using the semantic-ui-react library to implement Semantic UI components.

Generally we follow the InvenioRDM React component guidelines: https://inveniordm.docs.cern.ch/develop/best-practices/react/. Note, however, some points at which we diverge from the InvenioRDM guidelines (although not from the practice of some InvenioRDM developers):

• DO always prefer functional components over class components.

• DO employ React hooks (e.g., useState, useEffect, etc.) instead of class lifecycle methods.

Whatever the relative merits of class components, they are now deprecated in React and should not be used in KCWorks.

The InvenioRDM project also tends to use small React components embedded in static HTML generated by Jinja2 templates. This practice should be avoided in KCWorks. Instead, KCWorks should work towards implementing a true React-based UI layer that is used for all UI elements.

Where possible, however, KCWorks should employ built-in InvenioRDM UI components, overriding them where necessary using the react-overridable library as described here: https://inveniordm.docs.cern.ch/develop/howtos/override_components/.