Skip to content

Contributing Guide

Contributing Guide

Thank you for your interest in contributing! Follow these steps to get started using the command line. You could also use VS code to achieve the same results.

1. Clone the Repository

git clone https://github.com/Underwriters-Labs/ul-software-engineering-playbook.git
cd ul-software-engineering-playbook

2. Create a Branch

Create a new branch for your changes:

git checkout -b your-feature-branch

3. Make Changes

Edit or add files as needed.

4. Commit Your Changes

git add .
git commit -m "Describe your changes"

5. Push to GitHub

git push origin your-feature-branch

6. Create a Pull Request

  1. Go to the repository on GitHub.
  2. Click Compare & pull request.
  3. Add a description of your changes.
  4. Submit the pull request.

Authoring Guidelines

Formatting Code

Code for inclusion in the playbook docs should be formatted somewhat differently than code in a normal repository.

  • Code snippets using markdown should be enclosed in triple backticks (```) with the language specified after the first set of backticks (e.g., ```typescript or ```csharp).

  • When including blocks of code, ensure line lengths are short, ideally fewer than 800 characters, to ensure code samples can be read comfortable on a webpage without horizontal scrolling.

Don't

This code snippet is too wide, and will be difficult to read in the rendered documentation.

<!-- prettier-ignore -->
<div class="example">
  <p>This is an example of a code snippet that is too wide and will be difficult to read in the rendered documentation.</p>
  <p>It should be broken up into shorter lines to improve readability.</p>
  <input type="text" class="form-control" id="exampleInputEmail1" aria-describedby="emailHelp" placeholder="Enter email" style="width: 100%; max-width: 500px; margin: 0 auto;">
</div>

Do

This code snippet has shorter lines, making it easier to read in the rendered documentation. When viewing a diff in a pull request, consistently-formatted code reviews faster, and with fewer missed defects.

<div class="example">
  <p>
    This is an example of a code snippet that is too wide and will be difficult
    to read in the rendered documentation.
  </p>
  <p>It should be broken up into shorter lines to improve readability.</p>
  <input
    type="text"
    class="form-control"
    id="exampleInputEmail1"
    aria-describedby="emailHelp"
    placeholder="Enter email"
    style="width: 100%; max-width: 500px; margin: 0 auto;" />
</div>

Tools To Help

The repository is configured to use Prettier for code formatting, alongside git hooks and VS Code settings to ensure consistent formatting. This will help maintain the formatting standards outlined above, and ensure diffs are concise. Additionally, the .husky/pre-commit file is set up to run Prettier on staged files before committing.

  • Install Node.js and npm if you haven't already.
  • Use Node Version Manager (nvm) to manage Node.js versions, especially if you work with lots of Node projects.

  • You may need to restart your terminal after installing Node.js. You should be able to run node -v and npm -v to verify the installation.

  • Install NPM packages:

npm install
  • Install the Prettier extension for VS Code. Prettier for VS Code
  • Use the command npm run format:check to check formatting.
  • VS Code will automatically format files on save if you have the Prettier extension installed and configured.

Please ensure your changes follow the project's coding standards and include relevant documentation or tests.

Back to top