2 minutes read
No one likes when you’re put on a new project and there is no straight forward way to get started. Don’t be a terrible person, make your README useful!
How do you make it useful? I like to think, “if I have never seen this project before what would I need to know” or “in two months what will I need to know and I’ve already forgotten it”. After thinking of that generally you’re going to come up with a couple question you should answer.
Information that should be present
- What is this project?
- How do I spin up this project?
- Where are the environments this lives?
- Are there designs?
- Are there discovery docs or something useful that explains how things work?
- Any useful “gotchas” with this?
Other nice things to do
README allows for Markdown so you should format things in an easy-to-read way.
A Sample README
# My Sample Website
- Staging Site: [https://joshfabean.com](https://joshfabean.com)
- Git Repo: [https://git.joshfabean.com/fabean/drupal-config-split-sample](https://git.joshfabean.com/fabean/drupal-config-split-sample)
## Getting Started
This site is a Symfony website, that is using a plugin to allow us to output it as a static website.
- `fin up`
- `fin composer install`
- `npm install`
- `npm run build`
- `npm run watch` - if desired
## Generating Static Site
- `fin build-static-site`
- `fin serve-static-site`
## Theming
```
sample-website
│
└───resources
│ │
│ └───js
| | main.js
│ |
│ └───scss
│ │ styles.scss
| |
│ └───components
| your new components go here
│
└───templates
| base.html.twig
└───public
│ │
│ └───images
```
All twig templates go into the `templates` directory, you can create sub directories or place
right in there. Site seems it will be small enough we can just place straight in there. You should
also make a matching scss file for that component in the `resources/scss/components` directory.
You will also need to add your component to the base `styles.scss`
To add new components on the page edit `base.html.twig` include it and pass in all the variables needed.
```
{% include "header.twig" with {
'title': 'Hello World'
} %}
```
Adding assets like extra images, css, or js can be done with `{{ asset('/path/from/public/dir') }}`.
There will be need for using things like `<picture>` for responsive images.
## Deploying
This project follows our standard git flow and will deploy to staging with RC-vXXXX tags and for Prod we will be using RELEASE-vXXXX tags.
## Designs
## Team Leads
- Lead Developer: Josh Fabean
- Project Manager: Jash Fabean
- Designer: Anyone BUT Josh Fabean