In what file do I put the installation steps in my git repository?

Question

I have a git repository and I would like to add the installation steps required to make the project work locally. The project is a company and private project and users will also be contributors. I'm using GitLab.

But I don't know in what file to write these steps. I have several options in mind such as:

• the README.md file: it's the default page that users and contributors will see. But I fear too much information inside one file will make it hard to read.
• the CONTRIBUTING.md file: in my case, people who will install the project will be contributors. If they want to contribute, they will need to install the project locally..
• an INSTALL.md file: it's not recognized by GitLab as CONTRIBUTING and README are. But it's far more obvious in the name that it contains the installation steps.

What is the best practice in this case?

Answer 1

I like seeing INSTALL.md in a project. If I'm wondering "how do I install this?" then INSTALL.md is an obvious place to look.

In README.md add a small section about installation, and basically point people to the INSTALL.md file hosted in GitLab:

About Project

...

Contributing

..

Installation Instructions

See INSTALL.md for full instructions.

This gives you the best of both worlds. You get an appropriately named file and a link from the README file rendered in GitLab to the appropriately named file.

In fact this would work for GitHub, Azure DevOps or any other git hosting solution that does something special with the README file.