Project READMEs

• Purpose
• Template
• Other sections
  • Areas of expertise
• Related guides

Purpose

The README.md should be the initial point of reference for all developers working on a project. It should be kept up to date with the latest information about the project, including the tech stack, development environment setup, and any other relevant information. It should contain enough information for a new developer to get the project running on their local machine without additional input from other developers.

It does not need to explain domain-specific business logic or every variation from standard practice, but it should have enough information for the project to fully run on a developer's local machine.

TIP

If a more extensive record of business logic or more detail about third-party systems is required, create a docs folder in the project root and link to it from the README.md.

Template

Use the following as a starting point for new projects. Guidance notes appear as <!-- comments --> and should be removed (or replaced with real content) as you go.

<!--
A general introduction to the project should be written here: a brief overview
of the project's purpose, including relevant background about the client.
-->

ACME Widgets is a B2B ecommerce website, supplying widgets to small businesses around the UK and in Europe.

<!-- Include the pipeline badge if CI/CD is used: -->

![pipeline status](https://gitlab.morphsites.net/<namespace>/<project>/badges/main/pipeline.svg?ignore_skipped=true)

[TOC]

## Tech stack

<!--
List the technologies used in the project.
-->

- Laravel
- Inertia/Vue
- Typesense

## Time logging

<!--
Detail where time should be logged. If a single task/project is relevant, use
the format below.
-->

Time should be logged to the following task: [Task 12345: Development](https://link.to.task/).

<!-- If more than one time log is relevant, consider using a table instead: -->

| Project | Agencybeam Task | Description                                 |
| ------- | --------------- | ------------------------------------------- |
| General | Task 12345      | [Meetings and admin](https://link.to.task/) |
| General | Task 67890      | [Development](https://link.to.task/)        |

## Development environment

<!-- Detail the most common development environment setup here. -->

[Laravel Herd](https://standards.morphsites.net/development/local-development/laravel-herd.html) is the recommended local development environment.

<!--
If additional services are required, detail what they are and the recommended
way of setting them up. For example:
-->

**Typesense:** a [Docker Compose](https://standards.morphsites.net/development/local-development/docker.html) file is provided in the project. Run `docker compose up -d` to spin up a Typesense instance. Remember to stop the containers with `docker compose down` when you have finished working on the project.

## Formatting and analysis tools

<!--
List the tools active on the project.

Ensure these tools are enforced via an appropriate `.gitlab-ci.yml` file.
-->

The following are active on this project:

- [Laravel Pint](https://standards.morphsites.net/development/style/pint.html)
- [PHPStan](https://standards.morphsites.net/development/style/phpstan.html)
- [Prettier](https://standards.morphsites.net/development/style/prettier.html)

A GitLab pipeline enforces use of these tools.

Formatting and analysis may be performed manually with the following commands:

```shell
composer format
composer analyse
```

However, it is strongly recommended to configure your editor so these run automatically.

## Project setup

<!--
Detail the steps needed to get the project running locally. This template
assumes the project is using the morphsites/laravel-standards package, which
provides wrapper commands to handle common setup steps for Laravel projects.

If this package is not available on the project, provide detailed
instructions, listing every required step to get a running environment.
-->

After cloning the project, create a `.env` file from the `.env.example` file:

```shell
cp .env.example .env
```

<!--
IMPORTANT: Ensure that the `.env.example` file has sensible defaults for
local development.
-->

In the `.env` file, update `APP_URL` to match your development environment. If using Herd, this will likely be:

```dotenv
APP_URL=https://<project>.test
```

<!--
Detail the steps to configure and populate the database. Consider writing
seeders to provide dummy data that supports most local development.

If it is necessary to pull a copy of a database from a remote server, detail
how to do this.
-->

Ensure the `DB_*` variables in `.env` are suitable for your environment.

Then run the following command from the project root:

```shell
composer setup
```

This takes care of generating an app key, installing dependencies and migrating and seeding a database.

While working on the project, run the following command from the project root:

```shell
composer dev
```

This will run Vite, a queue worker and other services that are required for local development.

## Contributing

<!--
Use this section to detail contribution guidelines, including how
branches/features are managed on this project.

If the project adheres to one of the standard workflows, simply provide a
link. For example:
-->

This project adheres to the [basic workflow](https://standards.morphsites.net/development/git#basic-workflow). Please familiarise yourself with this standard before contributing.

<!--
Or:
-->

This project adheres to the [quality-assured workflow](https://standards.morphsites.net/development/git#quality-assured-workflow). Please familiarise yourself with this standard before contributing.

<!--
Detail any exceptions or additions to the standard.

If the project is not adhering to one of the standard workflows, explain why,
then detail the necessary steps.
-->

## Deployment

<!--
If the deployment process for this project is anything other than a standard
Forge deployment, detail it here. Include any details about deployment time
restrictions, required approvals, versioning, tagging or release cadence.
-->

Other sections

Feel free to add any other sections that may be relevant to the project. Of particular importance are:

• Any third-party platforms, services or APIs that are used
• Any implementations of business logic that would be surprising to another developer
• Common support issues and how to handle them

Areas of expertise

Large projects may benefit from a section detailing who the SME (subject matter expert) is for each project domain. For example:

## Areas of expertise

| Domain          | Contact         |
| --------------- | --------------- |
| Admin panel     | Miles O'Brien   |
| Auth            | Worf            |
| Error handling  | Q               |
| Notifications   | Data            |
| Ordering        | Jean-Luc Picard |
| Recommendations | William Riker   |
| Search          | Geordi La Forge |
| Support         | Deanna Troi     |

Related guides

• The Contributing section should align with the Git guide – adapt it if the project uses the quality-assured workflow.
• The tooling section should reflect the project's actual setup – see Code style & linting for the standard tools and commands.
• For environment setup details to reference, see Laravel Herd and Docker.