diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 71 |
1 files changed, 39 insertions, 32 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8847f0c2f..ab7ddff8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,15 +15,15 @@ This is the minimum open-source users should contribute back to the projects the ### Spread the word -Community growth allows the project to attract new talent willing to contribute. This talent is then developing new features and improves the project. These new features and improvements attract more users and so on. It is a loop. So, post about netdata, present it to local meetups you attend, let your online social network or twitter, facebook, reddit, etc. know you are using it. **The more people involved, the faster the project evolves**. +Community growth allows the project to attract new talent willing to contribute. This talent is then developing new features and improves the project. These new features and improvements attract more users and so on. It is a loop. So, post about Netdata, present it to local meetups you attend, let your online social network or twitter, facebook, reddit, etc. know you are using it. **The more people involved, the faster the project evolves**. ### Provide feedback -Is there anything that bothers you about netdata? Did you experience an issue while installing it or using it? Would you like to see it evolve to you need? Let us know. [Open a github issue](https://github.com/netdata/netdata/issues) to discuss it. Feedback is very important for open-source projects. We can't commit we will do everything, but your feedback influences our road-map significantly. **We rely on your feedback to make Netdata better**. +Is there anything that bothers you about Netdata? Did you experience an issue while installing it or using it? Would you like to see it evolve to you need? Let us know. [Open a github issue](https://github.com/netdata/netdata/issues) to discuss it. Feedback is very important for open-source projects. We can't commit we will do everything, but your feedback influences our road-map significantly. **We rely on your feedback to make Netdata better**. ### Translate some documentation -The [netdata localization project](https://github.com/netdata/localization) contains instructions on how to provide translations for parts of our documentation. Translating the entire documentation is a daunting task, but you can contribute as much as you like, even a single file. The Chinese translation effort has already begun and we are looking forward to more contributions. +The [Netdata localization project](https://github.com/netdata/localization) contains instructions on how to provide translations for parts of our documentation. Translating the entire documentation is a daunting task, but you can contribute as much as you like, even a single file. The Chinese translation effort has already begun and we are looking forward to more contributions. ### Sponsor a part of Netdata @@ -32,38 +32,45 @@ Netdata is a complex system, with many integrations for the various collectors, #### Sponsor a collector Netdata is all about simplicity and meaningful presentation. A "sponsor" for a collector does the following: - - Assists the devs with feedback on the charts. - - Specifies the alarms that would make sense for each metric. - - When the implementation passes QA, tests the implementation in production. - - Uses the charts and alarms in his/her day to day work and provides additional feedback. - - Requests additional improvements as things change (e.g. new versions of an API are available). + +- Assists the devs with feedback on the charts. +- Specifies the alarms that would make sense for each metric. +- When the implementation passes QA, tests the implementation in production. +- Uses the charts and alarms in his/her day to day work and provides additional feedback. +- Requests additional improvements as things change (e.g. new versions of an API are available). #### Sponsor a backend We already support various [backends](backends) and we intend to support more. A "sponsor" for a backend: -- Suggests ways in which the information in Netdata could best be exposed to the particular backend, to facilitate meaningful presentation. - - When the implementation passes QA, tests the implementation in production. -- Uses the backend in his/her day to day work and provides additional feedback, after the backend is delivered. - - Requests additional improvements as things change (e.g. new versions of the backend API are available). + +- Suggests ways in which the information in Netdata could best be exposed to the particular backend, to facilitate meaningful presentation. +- When the implementation passes QA, tests the implementation in production. +- Uses the backend in his/her day to day work and provides additional feedback, after the backend is delivered. +- Requests additional improvements as things change (e.g. new versions of the backend API are available). #### Sponsor a notification method Netdata delivers alarms via various [notification methods](health/notifications). A "sponsor" for a notification method: -- Points the devs to the documentation for the API and identifies any unusual features of interest (e.g. the ability in Slack to send a notification either to a channel or to a user). -- Uses the notification method in production and provides feedback. -- Requests additional improvements as things change (e.g. new versions of the API are available). + +- Points the devs to the documentation for the API and identifies any unusual features of interest (e.g. the ability in Slack to send a notification either to a channel or to a user). +- Uses the notification method in production and provides feedback. +- Requests additional improvements as things change (e.g. new versions of the API are available). ## Experienced Users ### Help other users -As the project grows, an increasing share of our time is spent on supporting this community of users in terms of answering questions, of helping users understand how netdata works and find their way with it. Helping other users is crucial. It allows the developers and maintainers of the project to focus on improving it. +As the project grows, an increasing share of our time is spent on supporting this community of users in terms of answering questions, of helping users understand how Netdata works and find their way with it. Helping other users is crucial. It allows the developers and maintainers of the project to focus on improving it. ### Improve documentation -All of our documentation is in markdown (.md) files inside the netdata GitHub project. All of our [HTML documentation](https://docs.netdata.cloud) is generated from these files. At the top right of each documentation page you will see a pencil, that leads you directly to the markdown file that was used to generated it. Don't be afraid to click it and edit any of these documents and submit a GitHub Pull Request with your corrections/additions. +Our documentation is in need of constant improvement and expansion. As Netdata's features grow, we need to clearly explain how each feature works and document all the possible configurations. And as Netdata's community grows, we need to improve existing documentation to make it more accessible to people of all skill levels. + +We also need to produce beginner-level tutorials on using Netdata to monitor common applications, web servers, and more. + +Start with the [guide for contributing to documentation](docs/contributing/contributing-documentation.md), and then review the [documentation style guide](docs/contributing/style-guide.md) for specifics on how we write our documentation. -We also need help to [document each chart in the default dashboard](https://github.com/netdata/netdata/issues/279). +Don't be afraid to submit a pull request with your corrections or additions! We need a lot of help and are willing to guide new contributors through the process. ## Developers @@ -71,16 +78,15 @@ We expect most contributions to be for new data collection plugins. You can read Of course we appreciate contributions for any other part of the NetData agent, including the [daemon](daemon), [backends for long term archiving](backends/), innovative ways of using the [REST API](web/api) to create cool [Custom Dashboards](web/gui/custom/) or to include NetData charts in other applications, similarly to what can be done with [Confluence](web/gui/confluence/). - ### Contributions Ground Rules #### Code of Conduct and CLA -We expect all contributors to abide by the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). For a pull request to be accepted, you will also need to accept the [netdata contributors license agreement](CONTRIBUTORS.md), as part of the PR process. +We expect all contributors to abide by the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). For a pull request to be accepted, you will also need to accept the [Netdata contributors license agreement](CONTRIBUTORS.md), as part of the PR process. #### Performance and efficiency -Everything on Netdata is about efficiency. We need netdata to always be the most lightweight monitoring solution available. We will reject to merge PRs that are not optimal in resource utilization and efficiency. +Everything on Netdata is about efficiency. We need Netdata to always be the most lightweight monitoring solution available. We will reject to merge PRs that are not optimal in resource utilization and efficiency. Of course there are cases that such technical excellence is either not reasonable or not feasible. In these cases, we may require the feature or code submitted to be by disabled by default. @@ -88,9 +94,9 @@ Of course there are cases that such technical excellence is either not reasonabl Unlike other monitoring solutions, Netdata requires all metrics collected to have some structure attached to them. So, Netdata metrics have a name, units, belong to a chart that has a title, a family, a context, belong to an application, etc. -This structure is what makes netdata different. Most other monitoring solution collect bulk metrics in terms of name-value pairs and then expect their users to give meaning to these metrics during visualization. This does not work. It is neither practical nor reasonable to give to someone 2000 metrics and let him/her visualize them in a meaningful way. +This structure is what makes Netdata different. Most other monitoring solution collect bulk metrics in terms of name-value pairs and then expect their users to give meaning to these metrics during visualization. This does not work. It is neither practical nor reasonable to give to someone 2000 metrics and let him/her visualize them in a meaningful way. -So, netdata requires all metrics to have a meaning at the time they are collected. We will reject to merge PRs that loosely collect just a "bunch of metrics", but we are very keen to help you fix this. +So, Netdata requires all metrics to have a meaning at the time they are collected. We will reject to merge PRs that loosely collect just a "bunch of metrics", but we are very keen to help you fix this. #### Automated Testing @@ -102,7 +108,7 @@ Of course, manual testing is always required. #### Netdata is a distributed application -Netdata is a distributed monitoring application. A few basic features can become quite complicated for such applications. We may reject features that alter or influence the nature of netdata, though we usually discuss the requirements with contributors and help them adapt their code to be better suited for Netdata. +Netdata is a distributed monitoring application. A few basic features can become quite complicated for such applications. We may reject features that alter or influence the nature of Netdata, though we usually discuss the requirements with contributors and help them adapt their code to be better suited for Netdata. #### Operating systems supported @@ -127,16 +133,18 @@ The single most important rule when writing code is this: *check the surrounding We use several different languages and have had contributions from several people with different styles. When in doubt, you can check similar existing code. For C contributions in particular, we try to respect the [Linux kernel style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html), with the following exceptions: - - Use 4 space indentation instead of 8 - - We occassionally have multiple statements on a single line (e.g. `if (a) b;`) - - Allow max line length of 120 chars - - Allow opening brace at the end of a function declaration: `function() {`. + +- Use 4 space indentation instead of 8 +- We occassionally have multiple statements on a single line (e.g. `if (a) b;`) +- Allow max line length of 120 chars +- Allow opening brace at the end of a function declaration: `function() {`. ### Your first pull request There are several guides for pull requests, such as the following: -- https://thenewstack.io/getting-legit-with-git-and-github-your-first-pull-request/ -- https://github.com/firstcontributions/first-contributions#first-contributions + +- <https://thenewstack.io/getting-legit-with-git-and-github-your-first-pull-request/> +- <https://github.com/firstcontributions/first-contributions#first-contributions> However, it's not always that simple. Our [PR approval process](#pr-approval-process) and the several merges we do every day may cause your fork to get behind the Netdata master. If you worked on something that has changed in the meantime, you will be required to do a git rebase, to bring your fork to the correct state. A very easy to follow guide on how to do it without learning all the intricacies of GitHub can be found [here](https://medium.com/@ruthmpardee/git-fork-workflow-using-rebase-587a144be470) @@ -150,5 +158,4 @@ We also have a series of automated checks running, such as linters to check code One special type of automated check is the "WIP" check. You may add "[WIP]" to the title of the PR, to tell us that the particular request is "Work In Progress" and should not be merged. You're still not done with it, you created it to get some feedback. When you're ready to get the final approvals and get it merged, just remove the "[WIP]" string from the title of your PR and the "WIP" check will pass. - -[]() +[](<>) |