Call for Implementation of an OpenELIS style Guide

Community Development
1

I would like to propose the creation of a comprehensive style guide and contribution reference for OpenELIS Global — one that spans the entire tech stack: backend, frontend, integration, and E2E tests, dataset conventions, and our UI design system.

As OpenELIS continues to grow and more contributors get involved, maintaining consistency across our stack will improve maintainability, reduce friction for new devs, and ensure smoother PR reviews.

what to cover in the guide:

Backend

  • Naming conventions (classes, fields, services)
  • Folder structure and layering
  • Exception handling, logging, and validation patterns
  • Integration test structure using datasets + DBUnit

Datasets

  • Naming conventions and organization
  • Minimal, clean test data principles
  • Use of schema validation

Frontend (React)

  • Component Structure and Folder Layout

  • Organize components by domain or feature, not by type (e.g., group PatientHeader, ConfirmPopup, etc. under common or relevant feature folders).

  • Each component lives in its own .js file, and related .css (if needed) lives alongside or in a common styles folder.

Naming Conventions

  • Component names use PascalCase.
  • File names match the component (e.g., CytologyCaseView.js).
  • Props should be descriptive and camelCased.
  • Contexts use SomethingContext or useSomething naming patterns.

Styling Guidelines

  • Use plain .css files; no CSS-in-JS
  • Reuse styles through shared CSS files where possible (PathologyDashboard.css).
  • Use BEM or scoped class naming to avoid global class conflicts.

Carbon Design System Integration

  • Use components directly from @carbon/react.
  • Always prefer Carbon-provided components unless business logic demands custom implementation.
  • Respect Carbon’s accessibility and responsive layout practices.
  • For icons, use only what’s available in @carbon/react/icons.

Other Principles

  • Use react-intl for all user-facing strings.
  • Favor state colocation via hooks (useState, useEffect, useRef) — no external state managers like Redux unless absolutely necessary.
  • Maintain clean separation of business logic and presentation within components.

E2E Testing (Cypress)

  • Naming structure and file organization
  • Setup and teardown practices
  • Interaction with test data / mocking vs real data strategy

:page_facing_up: Documentation & Dev Process

  • PR hygiene and checklist
  • Branch naming, commit message best practices
  • Prettier, ESLint, Spotless, and CI formatting enforcement

Initial Steps:

  • Create a Style guide in an OpenELIS Wiki.
  • Link it in CONTRIBUTING.md and in PULL_REQUEST_TEMPLATE.md.
  • Provide small usage examples and link to tooling configs.
6 Likes
2

In the context of trying to enlighten more about this especially in trying to distinguish between a design System and a Style guide, I have come across a few useful resources that were shared.

let me know if this is insightful and if there is any more consideration about it

4 Likes
3

Hi @Agaba_Derrick_Junior I think this is a fantastic idea, and I really appreciate your initiative on this! We are using Carbon just like OpenMRS, and so I think that is a perfect example, and perhaps we can re-use some of the same guidance to keep things aligned and make like easy for those who are contributing to O3 as well.

I would absolutely support the community taking this on, and working on making decisions on the community call on things like the naming conventions (some of which are covered in other places, but it needs to be brought together) and publishing the guide within our wiki and on Github. @Moses_Mutesasira and @Taib_Abdillahi I’m wondering if you guys can help to facilitate this on the OpenELIS community calls.

I anticipate this being a long-term project to get everything, though, so maybe we can also set a polished version as a goal for the next Google Docs season in February 2025, to to build on that work.

4 Likes
4

You are spot on. I’m interested in contributing to this community but my biggest challenge has been finding documentation.

1 Like
5

We will initiate the conversation on the next dev call on 1st May, 2025.

2 Likes
6

@caseyi thanks for the insight,
we will add this on the agender for the next call
cc @ Taib_Abdillahi
@Moses_Mutesasira

1 Like
7

hello @DebbieLou this readme can help you set up the environment
and the link to our Documentation

1 Like
8

Well received.

Thank you for the fast response.

1 Like
9

Hi @Agaba_Derrick_Junior,
I believe it’s a fantastic idea—and I’ve actually proposed E2E testing using Cypress in my GSoC proposal. As part of that, I’ve also included this part to help new contributors, covering:

Naming structure and file organization

Setup and teardown practices

Interaction with test data (mocking vs real data)

@Moses_Mutesasira @caseyi ,this should definitely be a topic to look at in my proposal, as it’s aimed at improving the onboarding and usability experience for those working on E2E tests.

2 Likes