1

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?

Improve this question
2
  • You could split it up into folders with a README.md per folder, and link to the various sections. I'm not on a computer that I can check, but if you navigate to a .MD file directly in GitLab, does it not show the formatted Markdown?
    – Cory
    Mar 3, 2020 at 15:45
  • Yes, it does show the formatted markdown when you go on .md file
    – vvvvv
    Mar 3, 2020 at 15:56

1 Answer 1

Reset to default
2

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.

Improve this answer
2
  • 1
    The link doesn't need to point specificly to the file hosted at gitlab - you can write a relative link to point to the file hosted next to the readme, or on a local workstation: [INSTALL.md](INSTALL.md)
    – bdsl
    Mar 4, 2020 at 7:54
  • Coming back late to accept this answer: this is what I enforced on all the repositories I manage :)
    – vvvvv
    Nov 10, 2020 at 21:22

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.