Add CONTRIBUTING.md

[paulfantom]

As we have some requirements before merging PR it would be good to create CONTRIBUTING.md doc with everything outlined.

Good template for such file is in https://github.com/nayafia/contributing-template

[ktsaou]

Yes, this would be nice!
We also have a checklist when new plugins are added.

[paulfantom]

I don't know what is the acceptance procedure, so I cannot write this doc. Who wants to do that?

[Ferroin]

I can cover the new-plugin checklist part, assuming that everyone is OK with what we already have on the wiki.

[ktsaou]

Yes, though it needs a little bit more info (charts.d is missing, several sections are python.d only, etc).

It does not request updating this page: https://github.com/firehol/netdata/wiki/Add-more-charts-to-netdata

It is also missing the infographic update.

[paulfantom]

It is also missing the infographic update.

No infographics in CONTRIBUTING.md please.

[ktsaou]

It should be updated somehow. If we don't add it there, we will have to do it...
The infographic is a file in the repo.

[Ferroin]

Yes, though it needs a little bit more info (charts.d is missing, several sections are python.d only, etc).

It does not request updating this page: https://github.com/firehol/netdata/wiki/Add-more-charts-to-netdata

Yeah, it could stand to be updated somewhat.

It should be updated somehow. If we don't add it there, we will have to do it...
The infographic is a file in the repo.

Are we sure we want random people updating the infographic though? I mean, that's one of the primary marketing tools, so it would be really good to have a smaller group of people doing it as appropriate. Also, given the highly condensed format being used, it's not exactly something that's easy for people to update.

[paulfantom]

CONTRIBUTING.md should be a simple text-only file. Not a book with pictures.

I mean, that's one of the primary marketing tools

And it definitely shouldn't contain any marketing.
One could say that nowadays README.md is for marketing

[Ferroin]

We're talking about requiring updating the infographic in README.md as an item in the module submission checklist, not embedding an infographic in CONTRIBUTING.md.

[paulfantom]

Sorry, I misunderstood you.

[ktsaou]

Are we sure we want random people updating the infographic though? I mean, that's one of the primary marketing tools, so it would be really good to have a smaller group of people doing it as appropriate. Also, given the highly condensed format being used, it's not exactly something that's easy for people to update.

You are probably right. This requires searching for a proper logo, adding it to a github issue to get a permanent high-speed URL, pasting it properly in draw.io to link the github URL - not the image itself, re-arranging a lot of other logos to make room, adding the new logo and linking it to the wiki page, saving the new infographic in png, adding it to a github issue to get another URL, editing README.md and the wiki home to replace the existing infographic image.

So, yes, this is subject to a lot of errors...

[cakrit]

Blocked By: #4394

[ktsaou]

I am ok with that.
I would add a list of maintainers for each plugin.

[paulfantom]

Question: Do we keep the following two as separate files? I think we should
CONTRIBUTORS.md
CODE_OF_CONDUCT.md

Yes, those are two different things.

[paulfantom]

I would add a list of maintainers for each plugin.

I propose do do this in a file header. This way it will be easier to find a maintainer when a PR touching such file is created.

[paulfantom]

@cakrit why this is blocked by #4394? CONTRIBUTING.md doesn't have anything to do with readme files. At least it shouldn't have.

[cakrit]

Contributing tells people what they need to do. Documentation is one of the things they need to do, it was already required in the PR guidelines. Each module needs a readme

[cakrit]

I propose do do this in a file header. This way it will be easier to find a maintainer when a PR touching such file is created.

Can you provide an example for a specific plugin? What would that header file look like?

[paulfantom]

CONTRIBUTING.md should contain a short guide on how people can help, not what they need to do.

[paulfantom]

As for header, simple:

# Maintainers: @paulfantom 

will be enough. It is similar to current "Author" section ex.

netdata/python.d/beanstalk.chart.py

Line 3 in 1ad4f1b

# Author: l2isbad

[ktsaou]

Do we possibly want to document the basic API in these too?

I think we should.

Now that we have moved all documentation inside the repo, it is clearly visible which sections are completely missing and which are not adequate.

I do like a lot the new structure though. Code and documentation together. A paradise for contributors...

I don't know of any other project that has embedded its documentation into the repo. Do you know any? We may be able to get a few ideas...

[Ferroin]

I don't know of any that embed it as separate files, but I do know quite a few that do it as inline documentation in the code itself. See for example the various Python-based modules in Ansible, they all have a docstring for the module itself that contains all the actual documentation for the module. I'm actually kind of against that approach personally though, because it will produce a number of files that are more documentation than code, and it can lead to unnecessary memory overhead for Python modules (the whole docstring for the module stays in memory for the whole time the module is loaded, which would translate to a roughly 300k+ increase in runtime memory overhead for the python.d plugin with everything enabled).

[Ferroin]

Also, When I finally get some time to work on it, I'll look at getting the python.d API documented in-tree.

[paulfantom]

We can write TBD in sections which are incomplete and finish them later.

[ktsaou]

A REFERENCE.md could be used in many places. This should document all the options available or APIs available, etc. So, developers could know that at least REFERENCE.md needs updating when things are added, removed or are changed.

So:

• README.md = end user description of what this is it and how it works
• REFERENCE.md = each and every option available for this
• CONTRIBUTING.md = documentation, how-tos, walk-throughs for contributing to this.

Also, to avoid deduplication we should somehow modularized common things. For example, the way simple patterns work is documented many times. But we have this: https://github.com/netdata/netdata/tree/master/libnetdata/simple_pattern - so every reference to "simple pattern" could be just a link.

The happens for sockets binding bind to settings in netdata. We could document them here https://github.com/netdata/netdata/tree/master/libnetdata/socket