Skip to main content

Get Started

We believe that technical documentation and example code is ideally stored in a repository instead of scattered around on Confluence pages. The philosophy is to make your documentation more accessible to the developers for whom they are intended. Bring your documentation to life in a guidelines repo. A guidelines repo can be as simple as one file with a list of rules, or can be elaborate containing detailed template for every type of project that exists in your organisation. The more details the guidelines contain, the better FirstMate can perform pull request reviews & generate code improvements.

1. Create a guideline repository​

Create a new repository, make sure the name contains the word guidelines.

FirstMate will be able to determine the guideline repository based on the file structure and repo-naming.

2. Add your first markdown file​

To start, you can simply add one GUIDELINES.md file in the main folder with some basic rules. We refer to our Standard Guideline repository as an example. There is no real template to follow, just use bullets and code examples.

3. Add subfolders [optional]​

You only need subfolders if you want to split best practices around infra-as-code, microservices etc. You should use categories and subcategories.

As an example, we refer to our own guideline repository.

/GUIDELINES.MD
/cat-1
    /GUIDELINES.MD
    /subcat-1
        /GUIDELINES.MD
    /subcat-2
        /GUIDELINES.MD
/cat-2
    /GUIDELINES.MD
    /subcat-3
        /GUIDELINES.MD
tip

It is preferred to create a guidelines template for every project type in your organisation. This will improve FirstMate's performance.

4. Add template folder [optional]​

To significantly lower the room for interpretation of guidelines, you can add example files or file structures in a template folder. Developers can also reuse this template into their projects.

If available, FirstMate uses the template implementation to review your pull requests. It will compare following aspects of the implementation:

  • Dockerfiles
  • Pipelines
  • Project structure
  • Unit test setup
  • Linter files
  • Configuration files

A project template does not have to contain a full project structure. If you only want to focus on an example docker file, or example pipeline implementations, you only add these files.

As an example, we refer to our own guideline repository.

tip

If you treat the template folder as a real project, it is much easier to be reused by your developers.