1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
# How to Contribute
Rsyslog is a real open source project and open to contributions.
By contributing, you help improve the state of logging as well as improve
your own professional profile. Contributing is easy, and there are options
for everyone - you do not need to be a developer.
These are many ways to contribute to the project:
* become a rsyslog ambassador and let other people know about rsyslog and how to utilize it for best results. Help rsyslog getting backlinks, be present on Internet news sites or at meetings you attend.
* help others by offering support on
* the rsyslog's github home at https://github.com/rsyslog/rsyslog
* the rsyslog mailing list at http://lists.adiscon.net/mailman/listinfo/rsyslog
* help with the documentation; you can either contribute
* to the [rsyslog doc directory](https://github.com/rsyslog/rsyslog-doc), which is shown on http://rsyslog.com/doc
* to the rsyslog project web site -- just ask us for account creation
* become a bug-hunter and help with testing rsyslog development releases
* help driving the rsyslog infrastructure with its web sites and the like
* help creating packages
* or, obviously, help with rsyslog code development
This list is not conclusive. There for sure are many more ways to contribute and if you find one, just let us know. We are very open to new suggestions and like to try out new things.
## When to submit Pull Requests?
It is OK to submit PRs that are not yet fully ready for merging. You want to
do this in order to get early CI system coverage for your patch. However,
all patches should be reasonably complete and "work" in a sense.
If you submit such PRs, please flag them as "work in progress" by adding
"WiP:" in front of the title. We will NOT merge these PRs before you tell us
they are now ready for merging.
If you just want/need to do a temporary experiment, you may open a PR, flag it
as "EXPERIMENT - DO NOT MERGE", let the CI tests run, check results and close
the PR thereafter. This prevents unnecessary cluttering of the open PR list.
We will take the liberty to close such PRs if they are left open for an
extended period of time.
Please note, though, that the rsyslog repo is fully set up to use Travis CI.
Travis covers about 95% of all essential testing. So we highly recommend
that you use Travis to do initial checks on your work and create the PR
only after this looks good. That saves both you and us some time.
## Requirements for patches
In order to ensure good code quality, after applying the path the code must
- no legacy configuration statements ($someSetting) must be added,
all configuration must be in v6+ style (RainerScript)
- compile cleanly without WARNING messages under both gcc and clang
- pass clang static analyzer without any report
- pass all CI tests
- new functionality must have associated
* testbench tests
* doc additions in the rsyslog-doc sister project
- be [sufficiently squashed](https://rainer.gerhards.net/2019/03/squash-your-pull-requests.html)
### Testbench Coverage
If you fix a bug that is not detected by the current testbench, it is
appreciated if you also add testbench test to make sure the problem does
not re-occur in the future.
In contrast to new feature PRs, this is not a hard requirement, but it
helps to speed up merging. If there is no testbench test added, the
core rsyslog developers will try to add one based on the patch. That
means merging needs to wait until we have time to do this.
### Compiler Diagnostics
Note that both warning messages and static analyzer warnings may be false
positives. We have decided to accept that fate and work around it (e.g. by
re-arranging the code, etc). Otherwise, we cannot use these useful features.
As a last resort, compiler warnings can be turned off via
#pragma diagnostic
directives. This should really only be done if there is no other known
way around it. If so, it should be applied to a single function, only and
not to full source file. Be sure to re-enable the warning after the function
in question. We have done this in some few cases ourselves, and if someone
can fix the root cause, we would appreciate help. But, again, this is a
last resort which should normally not be used.
Please read [on the importance of static analysis and why we request you to work around false positives](https://rainer.gerhards.net/2018/06/why-static-code-analysis.html).
### Continuous Integration Testing
All patches are run though our continuous integration system, which ensures
no regressions are inside the code as well as rsyslog project policies are
followed (as far as we can check in an automated way).
For pull requests submitted via github, these two conditions are
verified automatically. See the PR for potential failures. For patches
submitted otherwise, they will be verified semi-manually.
Also, patches are requested to not break the testbench. Unfortunately, the
current testbench has some racy tests, which are still useful enough so that
we do not want to disable them until the root cause has been found. If your
PR runs into something that you think is not related to your code, just sit
back and relax. The rsyslog core developer team reviews PRs regularly and
restarts tests which we know to look racy. If the problem persists, we will
contact you.
All PRs will be tested on a variety of systems, with the help of both Travis
CI and buildbot. The core goal of this multi-platform testing is to find
issues that surface only on some systems (e.g. 32bit related issues, etc).
We continuously strive to update the CI system coverage. If you can provide
a buildbot slave for a not-yet-supported test platform, please let us know.
We will gladly add it.
Note that test coverage differs between platforms. For example, not all
databases etc. are tested on each platform. Also note that due to resource
constraints some very lengthy tests are only execute on some (maybe only
a single) platform.
Note that we always try to merge with the most recent master branch and
try a build from that version (if automatic merging is possible). If this
test fails but no other, chances are good that there is an inter-PR issue.
If this happens, it is suggested to rebase to git master branch and update
the PR.
## Note to developers
Please address pull requests against the master branch.
## Testbench coding Tips
- look for similar tests and use them as copy template. Be sure to update
comments as well.
- see ./tests/diag.sh -- this is the base testing framework and it contains
many functions you can use inside your tests
- keep test cases simple and focussed on one topic. Otherwise it is hard to
address test failures when they happen in the future.
-------------------------------------------------------------------------------------
LEGAL GDPR NOTICE:
According to the European data protection laws (GDPR), we would like to make you
aware that contributing to rsyslog via git will permanently store the
name and email address you provide as well as the actual commit and the
time and date you made it inside git's version history. This is inevitable,
because it is a main feature git. If you are concerned about your
privacy, we strongly recommend to use
--author "anonymous <gdpr@example.com>"
together with your commit. Also please do NOT sign your commit in this case,
as that potentially could lead back to you. Please note that if you use your
real identity, the GDPR grants you the right to have this information removed
later. However, we have valid reasons why we cannot remove that information
later on. The reasons are:
* this would break git history and make future merges unworkable
* the rsyslog projects has legitimate interest to keep a permanent record of the
contributor identity, once given, for
- copyright verification
- being able to provide proof should a malicious commit be made
Please also note that your commit is public and as such will potentially be
processed by many third-parties. Git's distributed nature makes it impossible
to track where exactly your commit, and thus your personal data, will be stored
and be processed. If you would not like to accept this risk, please do either
commit anonymously or refrain from contributing to the rsyslog project.
-------------------------------------------------------------------------------------
|
