Skip to content

Developer guide

Julien Déramond edited this page May 11, 2023 · 7 revisions

This guide gathers good practices and elements that can help the developers to contribute to this project.

Reviews

Each pull request will be reviewed by:

  • 1 or 2 developers of the core team depending on the complexity
  • 1 designer if applicable
  • 1 accessibility expert if applicable

Philosophy: Consistency

Each modification of the source code must respect our philosophy: consistency. A change to fix an issue or for a new feature must take into account the existing code and propagate the new rules or modification everywhere in the code.

This philosphy is applicable for technical concepts, but also for the rendering, wording and code formatting.

Creating Issues and Pull Requests

Templates exist for issues and pull requests. They must be used and filled out in details to help with the efficiency of the core team. Too much details is better than no details.

Please don't forget to check all the elements in the lists.

GitHub Actions (CI)

Continuous integration is put in place thanks to GitHub Actions. Most of these GitHub Actions are executable locally. The detailed commands are available in our package.json in the scripts section.

Migration guide

Based on the users' feedback, we are maintaining a detailed migration guide between versions. Each PR should be evaluated in terms of impact for the end-user:

  • Change of HTML markup in components, documentation and examples
  • New/deprecated features or components
  • New/deprecated Sass/CSS variables

CSS and Sass

Most of the time, when new variables are added (CSS or Sass), it must be reflected in the documentation thanks to the <code>scss-docs</code> shortcode.

New components

New components have their own docs pages, Sass files, JavaScript code and tests. But they can also be mentioned somewhere else in the documentation. Here is a list of places not to forget:

  • in /about/overview/#custom-components if it is an Orange custom component
  • in /getting-started/introduction/#components if it is a new Orange custom component that requires JavaScript (and Popper)
  • in <code>/customize/overview#csps-and-embedded-svgs</code> if it is a new Orange custom component that includes embedded SVGs in our CSS
  • in <code>/forms/validation/?#supported-elements</code> if it is a new Orange custom component that is a form control
  • in <code>/forms/overview/</code> if it is a new Orange custom component that is a form control

Documentation design

A hidden URL is available in the documentation to check more easily some reusable elements of this documentation. It is available at /docsref/ (e.g., https://main--boosted.netlify.app/docsref/).