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 forums at http://kb.monitorware.com/rsyslog-f40.html
- 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, which is shown on http://rsyslog.com/doc
- to the rsyslog project web site -- just ask us for account creation
- on the rsyslog wiki at http://wiki.rsyslog.com/
- become a bug-hunter and help with testing rsyslog development releases
- help driving the rsyslog infrastructure with its web sites, wikis 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.
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 more than a day or two.
Please note, though, that the rsyslog repro 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.
In order to ensure good code quality, after applying the path the code must
- no legacy configration 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
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 ourselfs, 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.
Continous Integration Testing .............................
All patches are run though our continous 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 automatted way).
For pull requests submitted via github, these two conditions are verified automatically. See the PR for potential failueres. 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 continously 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.
Please adress pull requests against the master branch.