How to make a patch for VyOS

It’s very cool we are getting more and more contributors, and the code is great, but now it seems that our development procedures are poorly specified and/or difficult to get into. So here’s the guide.

Background

VyOS is a large project, we have around 70 packages we build from source now. This creates certain challenges in making changes and tracking them. Sometimes adding features or fixing bugs needs changes in several packages, sometimes single feature does not correspond to single package. This is one of the reasons we do not use github issues: it simply lacks tools to reflect this (the other reason is vendor lock-in of course).

To simplify things, certain procedures exist.

What maintainers do

We have a bugtracker (http://bugzilla.vyos.net). Bugtracker is not just a tool for users to report bugs, it’s also a tool for developers to communicate their changes, and a tool for maintainers to track progress (in corporate world that’s project manager’s work). In this guide we refer to both bugs as mistakes/defects and enhancement requests as just bugs.

Milestones

The bugtracker has “target milestones” that correspond to releases. When maintainers decide a bugfix or enhancement is to be included in certain release, they set its target milestone to that release. Entries with same target milestone essentially form the release roadmap.

When the work is complete, that bugtracker entry resolution is set to “RESOLVED, FIXED”. When all bugs scheduled for release are resolved, it means release can be made.

Connecting git and bugtracker

Bug resolution (usually) looks like one or more commits in git. To simplify tracking changes, commit messages should refer to bugs they resolve, and bugtracker entries should include links to those commits. Otherwise answering the question “why this change was made” or “how was this fixed” easily becomes tricky. Especially when it requires changes in multiple packages. If all packages have commits like “Bug #42: ${change description}” and the bug has links to all those commits, it’s easy.

The procedure

So, the overall procedure ideally looks like:

1. Search for existing bugs about your problem or feature idea. If it doesn’t exist, create it.
2. Write some code. Include bug number in commit descriptions when you are ready to send the patch, like “Bug #42: …”. Send a patch/make a pull request.
3. When the patch is merged, make sure bug comments have links to relevant commits.

Following this procedure will save you and maintainers substantial amount of time.