About

I had the chance to start numerous projects throughout my career.
Some were successful projects managed by a big team of developers. Others died.

I've seen people struggling to start a new project. It's like a blank canvas, you have a lot of freedom, but things can go wild. And throughout the years, some patterns emerged. Something that we've ended up using anyways, regardless of whether we set them up in the beginning.

This page is my take on defining a list of best practices you can follow when starting a new project. There are things you can do to lay yourself, and your team, for success. An explanation for each item is given, along with a basic categorization.

If you believe the list can be improved, please send me a letter or open an issue on GitHub . It's an open effort for everyone to join.

Good luck!

Chapter 1: Foundation

01 — Repository

Version Control System (VCS) is the base of any software project and is nowadays considered a must. You can read more on why you should use VCS.

1.1. Configure repository important

Regardless if you're creating a new repo, or checking out an existing one, you need to configure your VCS client. The following chapter gives a guideline on how (and why) to setup a git client.

1.1.A Set git `name` and `email`

Git supports different configurations per repository. Its flexibility allows us to use separate credentials for each project, which comes in handy especially in open-source projects.

That's why it's crucial that you configure your local repository to use the appropriate name and email:

git config user.name # shows your current name
git config user.email # show your current email

git config user.name "John Doe" # set name in current repository
git config user.email "john@doe.com" # set email in current repository

Note: If you're not using multiple identities, you can configure a global username & password that would work for each repository.

1.1.B Configure `lf/crlf`

Different operating systems use different invisible character to define a "line ending". If collaborators work in various systems, it could lead to problems. Making a simple change in a file might result in hundreds of modifications, because the operating system would transform all line endings.

The best way to tackle this is to configure your IDE to use the same line endings, using .editorconfig file:

# .editorconfig file in root of your project
[*] # every file
end_of_line = lf # unix-style newlines with a newline ending

git comes with a mechanism to convert those for you, enforcing the same end result for everyone:

# sample, check https://stackoverflow.com/questions/1967370/git-replacing-lf-with-crlf

1.2. Add `.gitignore` file important

https://www.datree.io/resources/github-best-practices

https://www.toptal.com/developers/gitignore/

This one requires no explanation, but is often missed. It should include all app-specific folders (www for Angular, build for React, dist for Vue, etc), along with node_modules and any sensitive containing ones (.aws).

1.3. Protect master branch great

02 — Basics

2.1. Repo type: single / mono / multi important

2.1.A Switch package manager great

2.2. Choose a suitable git workflow important

2.3. Define commits convention important

2.3.A Enforce with a pre-commit hook great

2.4. Create a proper `README.md` great

Too obvious, but neglected way too often! The file is the entry point of your repository and the first thing people see. It should contain a brief explanation of what the code does, as well as instructions how to use it.

The main goal is to ease others (or even yourself) using your code. It's not uncommon to return to a project after a long time, and be unsure of how it worked before. The file should contain as much concise information as possible:

What is this project for
Instructions how to run it on your machine important
- System requirements
Links to other documents important
- Contributing, Code of Conduct
Basic list of technologies used
Roles and responsibilities
Points of contact

TODO: sample

03 — Code Quality

3.1. Static code analysis & formatting important

By definition, static analysis "identifies and fixes defects before you run a program". But it's even more than that. It helps your code stay cohesive regardless of the developers count, their seniority or experience. It makes work easier and safer.

One of the first things to setup is a linter/formatter. You can use ESLint for JavaScript, TSLint for TypeScript or even go further with Prettier .

Regardless of your choice, your main task is to setup the foundation for a clean code.

So make sure it lints! important - you'll add rules with time.

3.1.A Enable auto fix / code format great

3.1.B Configure `git` pre-commit hook great

3.1.C Files & folders linting extra

3.2. Define testing strategy important

3.2.A Working test suite great

3.2.B Configure test coverage tool extra

Chapter 2: Development

04 — Define & scope

4.1. Define target browsers & devices important

4.1.A Configure browsers list important

4.2. Accessibility (`a11y`) great

4.3. Internationalization (`i18y`) extra

4.4. Documentation important

4.4.A Automated `CHANGELOG` great

4.4.B Architectural Decision Records `ADRs` extra

05 — Bootstrap

5.1. `create-x-app`

06 — Styling

6.1. Pick methodology / framework important

6.2. Global normalize/reset important

6.3. Sizing (em/rem/px) great

6.4. Responsiveness great

6.5. Preprocessors / modules? extra

Chapter 3: Delivery

07 — Pack

7.1. Build for Production

08 — Optimize

8.1. Minify resources great

8.2. Speed it up

8.2.A Measure speed

09 — Ship

9.1. CI/CD pipeline

CI/CD sounds very complex and something the DevOps team should typically do. But the truth is, you don't have to be a magician in order to set it up. Gone are the days when you had to have a masters degree for that.

Your CI/CD pipeline is your project's automatic gatekeeper and a best friend of yours. Ideally, it should:

Lint your code, making sure messed up code does not enter the repository
Run unit tests so your code always stays functional
Run e2e tests, if you have some, so your code works as best as it can
Deploy your code so your results are always online

Some of those points might not seems meaningful right away. But it's important to set up a solid foundation to build upon!

Most of the tools nowadays (TODO: link to GitHub, GitLab, BitBucket) work almost the same way. They use a file describing the pipeline, with different steps.
Do something basic - implement an empty pipeline that runs your feature branches, and simply log a message. If you have follow the list and already set up a test suite (TODO: internal link to testing section you can run the tests and get a "passed" sign.

Good enough to build upon!

9.2. Streamlined releases

Go up