DOCSEARCHbyAlgolia
Submit Docs

MSML Code Guidelines

website·Indexed 30 days ago

https://guidelines.msml.io/

Development standards and best practices for MSML projects, including guidelines for Laravel, React Native, BootstrapVue, Mantine, CSS/SCSS, and Git repository naming conventions.

Tokens
6.8K
Snippets
39
Records
50
Agent score
43%

What's inside MSML

  1. Overview of MSML Code Guidelines

    The MSML Code Guidelines provide a comprehensive collection of coding standards, best practices, and processes to ensure consistency, maintainability, and quality across all MSML projects. The documentation covers the following key areas:

    • Code Guidelines: Standards for Laravel & PHP (backend), React & React Native (frontend/mobile), and Stylesheets.
    • Deployment: Step-by-step deployment guides and CI/CD workflows.
    • Version Control & Git: Branching strategies, commit conventions, and versioning practices.
    • Style Guides: Brand standards, design system components, and UX/UI guidelines.

  2. Implement type safety and declarations in PHP

    Follow these rules for type declarations to improve code clarity and IDE support:

    • Typed Properties: Always type properties directly; avoid using docblocks for types unless necessary.
    • Void Returns: Explicitly use the void return type for methods that do not return a value.
    • Nullable Types: Use the short nullable syntax (?type) instead of union types with null.
    • Enums: Use PascalCase for enum case values.
    class Order {
    public string $status; // Typed property
    public ?int $userId;    // Short nullable syntax
}

public function sendNotification(): void {
    // Void return type
}

enum PaymentStatus {
    case Pending;
    case Completed;
}

  3. Apply scoped styles with CSS Modules

    Use .module.css files to define scoped styles for custom components or complex styles that cannot be handled by Mantine props or theme overrides. This prevents CSS conflicts and maintains separation of concerns.
    /* layout.module.css */
.container {
  max-width: 100%;
  @media (min-width: $mantine-breakpoint-lg) {
    max-width: 86rem;
  }
}
    import styles from './Layout.module.css';
import { Container } from '@mantine/core';

export function CustomLayout({ children }) {
  return <Container p={0} className={styles.container}>{children}</Container>;
}

  4. Name branches based on issue type

    Branches must follow specific naming conventions based on the ticket type. Pull requests from branches that do not follow these conventions will be rejected.

    • Story (Sprint features): feature/{ticketNumber}-kebab-case-description (Example: feature/MSML-123-add-login-page)
    • Service Request (Support board): service/{ticketNumber}-kebab-case-description (Example: service/MSMLS-456-update-footer-links)
    • Bug (Support board): hotfix/{ticketNumber}-kebab-case-description (Example: hotfix/MSMLS-789-fix-header-crash)
    • Maintenance/Security/Access: Use the Story convention if part of a sprint, or the Service Request convention if from the support board.

  5. Manage production deployments with Release Branches

    Release branches are used to manage production deployments and must always remain stable.

    • Naming Convention: release/v{major}.{minor}.x (Example: release/v3.23.x)
    • PR Requirements: PRs from hotfix/service branches to the release branch require review by one senior developer and one medior developer from the project team.
    • Deployment: After merging the PR, create a GitHub tag (e.g., v1.0.1) to trigger the production deployment.

  6. Define public-facing URL structures

    All public-facing URLs must use kebab-case to ensure consistency and readability.
    // Good
https://msml.nl/about-us
https://msml.nl/blog/software-development-tips

// Bad
https://msml.nl/AboutUs

  7. Organize SCSS file structure

    Use a single import file (e.g., app.scss) as a webpack mix. All files imported into this main file must be prefixed with an underscore (e.g., _variables.scss) to indicate they are partials. Organize styles into the following directory structure:

    • Core: Global styling (animations, base styles, typography, variables).
    • Layouts: Styling for specific page layouts (e.g., auth screens).
    • Elements: Overrides for framework-predefined components. File names must match the framework component name (e.g., buttons.scss, not primary-button.scss).
    • Components: Styling for custom-made components or third-party imports (e.g., footers, sidebars, multiselects).
    // Core
@import 'core/animation';
@import 'core/base';
@import 'core/typography';
@import 'core/variables';

// Layouts
@import 'layouts/app';
@import 'layouts/auth';

// Elements (Framework overrides)
@import 'elements/buttons';
@import 'elements/cards';
@import 'elements/dropdowns';

// Components (Custom/External)
@import 'components/footer';
@import 'components/sidebar';
@import 'components/multiselect';

  8. Name variables when passing data from controllers to views

    When passing data from a controller to a Blade template via a data array, use snake_case for the keys. This aligns with traditional Laravel conventions and improves readability within Blade templates.

  9. Contribute to MSML Code Guidelines

    The MSML Code Guidelines are a living resource. Developers can contribute improvements, report outdated information, or suggest changes by submitting a pull request to the official GitHub repository.
    # Repository for contributions
https://github.com/msmlbv/guidelines

  10. Execute branch workflows by issue type

    The workflow for merging changes depends on the nature of the task:

    • Story: Branch from master $\rightarrow$ Push $\rightarrow$ PR to master $\rightarrow$ Review/Approve.
    • Service Request: Branch from latest release/vx.x.x $\rightarrow$ Push $\rightarrow$ Draft PR to release/vx.x.x $\rightarrow$ PR to master $\rightarrow$ Review/Approve.
    • Bug: Branch from latest release/vx.x.x $\rightarrow$ Push $\rightarrow$ PR to release/vx.x.x $\rightarrow$ Review/Approve $\rightarrow$ Backmerge from release/vx.x.x to master.
    • Maintenance/Security/Access: Follow the Story workflow for sprint items or the Service Request workflow for support items.

    Critical: Never merge the master branch back into a release branch.

  11. Apply general PHP code style and naming standards

    All code must adhere to PSR-1, PSR-2, and PSR-12 standards. Use the following naming conventions:

    • Variables and method names: camelCase
    • Class names: PascalCase
    • Constants: UPPER_SNAKE_CASE
    $activeUsersCount = 42; // camelCase
class UserManagement {} // PascalCase
define('MAX_LOGIN_ATTEMPTS', 3); // UPPER_SNAKE_CASE

  12. Organize Modals in React Native Project Structure

    Modals must be placed in App/Container/Modals/. Each modal requires its own dedicated folder named after the modal. Inside that folder, there must be a component file with the Modal suffix and a corresponding style file with the Style suffix.
    App/Container/Modals/
└── SelectModal/
    ├── SelectModal.js
    └── SelectModalStyle.js