-
Notifications
You must be signed in to change notification settings - Fork 475
OSE maintenance workflow
This is a documentation about the syslog-ng OSE work flows as used by Gergely Nagy. The aim is to shed some light on how syslog-ng has been managed recently: the tools and processes used, and some hints on how to handle frequently occurring events.
A number of tools are used for OSE development, and I'll start this documentation with enumerating them, so that I can refer to them later, without having to explain their purpose.
The source code is on GitHub, we're using GitHub Issues for bug reports, questions, feature requests and all kinds of other issues. They are often tagged with various helpful tags, and in many cases, they're assigned a milestone. Milestones are usually releases, everything within a milestone must be completed before a release can be made. While that is not a technical requirement, it is one worth following. Of course, one can freely move issues between milestones. Milestones can also have a deadline, which can serve as an estimate for the release date. One can also add a description, which may serve as a road-map of some sort, but we have not done that before. We'll talk a bit more about milestones when we get to release handling.
While GitHub issues are a great building block, they aren't the easiest thing to glance through quickly. Therefore, we are also using waffle.io, which is a Kanban board built on top of GitHub issues. With this tool, one can prioritise issues, and drag them into the appropriate column (which is a GitHub label under the hood). The tool also offers a few settings, of which column customisation is the handiest. There are also metrics, but at the time of writing, those aren't terribly useful.
For testing, we are using Travis CI, which is controlled
by a .travis.yml file within the syslog-ng source tree. Please
consult the Travis CI documentation regarding that file.
For every tag and push, Travis CI will run the tests, likewise for pull requests.
To cover more ground, we are also using drone.io
alongside Travis. The tests run by this service are only run for
pushes, not for tags or pull requests. Compared to Travis, drone.io
does things a bit differently: it does a make distcheck, while
Travis does not.
We were also experimenting with Coveralls, but didn't get far yet.
There is a single repository for syslog-ng, with multiple master-like
branches for the different, still actively maintained branches. The
master branch is always the main development branch, while
$VERSION/master is the master branch of the appropriate syslog-ng
version.
The default branch on GitHub is usually the development branch
(master), unless a new release is nearing release, in which case the
default branch should be set to that one.
Whenever there is an issue, either opened by a user, or found internally, the first thing to do is tag it: be it a bug, an enhancement, a question, or a documentation bug - just tag it! Then one can prioritise it on waffle.io. The faster it is moved to the appropriate spot, the less likely it will fall down and get forgotten. If possible, attach the issue to a milestone as soon as possible, too!
Most public communication regarding an issue should happen in the issue itself. It is a good idea to learn GitHub-flavored Markdown, as that makes it easier to write comments that are easy to read. For example, if one wants to insert a config snippet, a fenced code block is an easy way to do that. Furthermore, when referring to functions, inline code formatting can be used to make the function name visually different from normal text. When it comes to the open source community, communication is paramount, therefore mastering the markup language is a great asset in one's toolbox. This also applies to commit messages: clear, concise and well formatted commit messages are amazingly useful for both users, contributors and for anyone - future you included! - looking at the history in search of information.
Once an issue is resolved, there are different ways on how it can be closed:
-
One can close it with a commit to the main branch. See this post for an explanation how that is done.
This is the preferred way of closing an issue, because it provides a clear reference in history, and it will be easy to figure out which patch or set of patches fixed a particular issue.
Do note that one can use a merge commit to close the issue too! Just write
"Fixes #$NUMBER"when pushing the merge button, and prompted for a merge message. -
Drag the issue to the
Donecolumn on waffle.io. This is easy to do, in case one forgot to close the issue from a commit, or when there is no need for a commit to fix it (such as an answered question, or a bug already fixed, and so on). -
It is also possible - of course - to close the issue on GitHub itself.
In case an issue is deemed unnecessary to fix, apply the wontfix
label, and keep it open, so duplicates aren't opened.
For every release, there should be a milestone, under which all relevant issues shall be placed. Once a release is ready and out, the milestone must be marked closed. When closing a milestone, move any still open issues out of it.
Releases are tagged with syslog-ng-$VERSION, after the VERSION and
NEWS.md files were updated. Then, the appropriate NEWS section is
copied to the GitHub release notes, by creating a
new release and typing the tag name into the appropriate field. If the
release is a pre-release, that box should be ticked too.
The OSE website uses these GitHub
releases to display download links. Simply tagging is not enough. To
help distributions that prefer make dist tarballs over git archives,
prepare such a file, and attach it to the GitHub release.
In general, we try to maintain API and ABI compatibility within a stable branch, and we only backport bugfixes. Some smaller features (or things that border on the bug/feature level) may creep in, but that is discouraged.
Before doing a release, have a look at lib/Makefile.am, on the
LSNG_CURRENT, LSNG_REVISION and LSNG_AGE variables, and follow
the guidelines above those. When releasing a new major version, set
all of these to zero, as soon as the version in VERSION is upped.
New releases should be announced on the mailing list and twitter too.