Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add CONTRIBUTING.md document #146

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add CONTRIBUTING.md document #146

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Contributing

The Prometheus Community welcomes contributions to the node_exporter textfile
collector script repository adhering to the following criteria:

Ideally, scripts should not duplicate functionality that is already available in
dedicated exporters. The textfile collector script collection is largely
intended to provide stop-gap measures, parsing output from third-party tools
(e.g. RAID controller utilities), or in situations where elevated privileges
(e.g. root access) are required.

Textfile collector scripts should be written in either Python or shell script.
Scripts are expected to output metrics to `stdout` in the [Prometheus text-based
format][1], and should not directly write to an output file.

Metric and label names should follow the Prometheus [naming guidelines][2].

## Python Scripts
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How should Python scripts state requirements beyond prometheus-client?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One idea, we could move to having directory-per-script and requirements.txt files for python scripts.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, that's certainly possible. I am a Python noob, especially on tooling, so is there a way to do pip install github.com:org/repo/subfolder#revision or something similar?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not really. you can pip install . from within a directory, but typically you'd ship this whole project as one big project on pypi and install it as one chunk.

that said, i am not sure you'd want to set that as policy right now. i would suggest you start with the drafted policy as is, and then maybe iterate once this PR is merged, as python packaging is rather more complicated than, say, shell scripts.

personnally, i wouldn't do the requirements.txt dance at all and keep things at a simple one-file-per-script approach. more complicated exporters should just have their own git projects IMHO.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like @anarcat, I think that once something crosses the threshold of being pip-installable, it really ought to move to its own repo which can better cater to its needs such as having a requirements.txt, and the main focus of that repo being $foo.

If we were going to make this repo pip-installable, I think we would need to more accurately define what the mission of this repo is. At present, it's just a jumble of unrelated textfile collector scripts, which is fine - so long as it doesn't promise to be anything more.


- Must use Python 3.x.
- Must use the official Prometheus Python [client library][3], which greatly
simplifies ensuring valid metric output format.
- Must pass a [flake8][4] lint check (enforced by CI pipeline).

## Shell Scripts

- Must use either Bash or generic POSIX-compatible shell (e.g. `/bin/sh`).
- Must pass a [shellcheck][5] lint check (enforced by CI pipeline).
- With the exception of specific third-party / closed-source tools, should avoid
using "exotic" commands that are unlikely to be present on typical systems.

[1]: https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format
[2]: https://prometheus.io/docs/practices/naming/
[3]: https://github.com/prometheus/client_python
[4]: https://flake8.pycqa.org/
[5]: https://www.shellcheck.net/