search

greenbone / templates

Greenbone Templates for repositories on GitHub
Creative Commons Attribution Share Alike 4.0 International
3 stars 18 forks source link

Suggestion to use a consistent "prerequisites" part in all INSTALL.md #17

Open cfi-gb opened 5 years ago

cfi-gb commented 5 years ago

Each main component like GVMd, GSA, openvas, GVM-Libs seems to either miss the required "prerequisites" for building it completely or using an inconsistent style when comparing it with other components.

It might make sense to provide an INSTALL.md template containing an example as suggested by @mattmundell in https://github.com/greenbone/gvmd/pull/741#discussion_r321963671

This is confusing because there's another section for optional features below.

I think it would be clearer if there was an apt command below each case above. So, one command below "Prerequisites for certificate generation", one below "Prerequisites for S/MIME suport (e.g. email encryption)" etc.

davidak commented 5 years ago

Such a section should be called Requirements and belongs in the README, as the template shows: https://github.com/greenbone/templates/blob/master/README-template.md#requirements

We can add an example for optional dependencies there.

INSTALL.md should only be used for INSTALL instructions, if they are so long that they don't fit into the README. We can add an example for that.

cfi-gb commented 5 years ago

@davidak in https://github.com/greenbone/gvmd/pull/741#discussion_r322320062:

How to install the dependencies on debian is quiet special and might be better in an additional file. Figuring that out is a task for people packaging the software for the distros. In best case, a user should only install a package and everything is working as expected. We can link to community maintained packages. See for example: https://repology.org/project/gvmd/versions

The INSTALL.md contains also many informations that belongs in the Usage section or external documentation, but that's a different topic.

cfi-gb commented 5 years ago

The main problems seems to be here to differ between two things:

  1. Installation / run-time prerequisites for the component
  2. Build prerequisites for the component

In the example of e.g. https://github.com/greenbone/gvmd/pull/741#discussion_r322320062 things like "GnuTLS certtool", "GNU privacy guard - S/MIME version" and "PostgreSQL database" seems to fit into 1. where e.g. cmake is only required for building.

When specifically looking into the INSTALL.md of GVMd e.g. "Migrating from SQLite to PostgreSQL" is also not really an INSTALL instruction and would better fit into a different file.

I currently don't have a clear approach on how to improve those points but a complete overhaul of the INSTALL.md of each main component (GVMd, GVM-Libs, OpenVAS, GSA) could make sense.

cfi-gb commented 5 years ago

In addition to the points above an "Installation" is currently possible in a few ways:

  1. Build (compile) the components from source
  2. Use a community maintained package
  3. Use a pre-configured Docker Image
  4. Use the GCE VM

where 1. and 2. share the same steps like e.g. setting up the database connection, generating certificates, ...

This could be a starting point to split the build/compile steps (including the required build dependencies) from the INSTALL.md into a new BUILD.md and rename the INSTALL.md into e.g. SETUP.md. Afterwards the README.md could point out the installation methods and link to the resources accordingly.

wiegandm commented 5 years ago

I agree that it makes sense (especially for C modules) to distinguish between dependencies required at build time vs. at run time.

I also agree with @cfi-gb that installing is possible in many ways, with building from source probably the least used among non-developers.

Based on the suggestions by @cfi-gb and @davidak, I would propose the following:

@cfi-gb, @davidak: Any objections?

wiegandm commented 5 years ago

After talking this over with @davidak, I agree that a separate BUILD.md is probably not strictly required. My aim with this was a clear separation of dependency types, but this can also be achieved by a properly structured INSTALL.md.

cfi-gb commented 5 years ago

Sounds indeed good and i agree that BUILD.md is not absolutely mandatory if the INSTALL.md is properly structured.

We only need to be aware that pointing users at distro / third party repositories might have a drawback that users might use outdated versions of our components causing e.g. bugreports or community portal postings for already fixed stuff.

cfi-gb commented 4 years ago

https://github.com/greenbone/gvmd/pull/1242 is now using a different approach, maybe we can use the same for all other C-based components.