CONTRIBUTING.md

Contributing to wayvnc

Commit Messages

Please, try to write good commit messages. Do your best to follow these 7 rules, borrowed from Chris Beams, plus 1 extra rule:

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how
8. (Extra) Prefix the subject line with the component that's modified

If you wish to know why we follow these rules, please read Chris Beams' blog entry, linked above.

Rule number 8 allows us to quickly gauge if a given commit is relevant to what we're looking for when skimming the log. It adds consistency and simplifies the message. For example

ctl-client: Print trailing newline for events

is better than

Print trailing newline for events in ctl-client

Example:

ctl-client: Print trailing newline for events

If someone wants to parse this instead of using jq, a trailing
newline delimits the end of the event.

Style

This project follows the the Linux kernel's style guide as far as coding style is concerned, with the following exceptions:

• When declaring pointer variables, the asterisk (*) is placed on the left with the type rather than the variable name. Declaring multiple variables in the same line is not allowed.
• Wrapped argument lists should not be aligned. Use two tabs instead. There is a lot of code that uses aligned argument lists in the project, but I have come to the conclusion that these alignments are not very nice to maintain.

Summary & Examples:

In case you aren't familiar with Linux's coding style, here is a short summary and some examples of acceptable formatting:

• Use tabs for indenting.
• We do not align code (mostly), but when we do, we use spaces rather than tabs. This rule is not according to the Linux style guide.
• The preferred limit on the length of a single line is 80 columns.
• User-visible string such as log messages must not be split up.
• Use space after the following keywords: if, switch, case, for, do, while.
• Do not use space after others such as: sizeof, typeof, alignof or __attribute__.
• Do not use typedefs.
• It is allowed to use typedefs for function pointers. This rule is not according to the Linux style guide.

Functions

static int do_something(int number, const char* text)
{
	body of function
}

if

	// Single statement
	if (condition)
		do_this();

	// Multiple statements
	if (condition) {
		do_this(2, "41");
		do_that();
	}

	// Single statement if/else
	if (condition)
		do_this();
	else
		do_that();

	// Multi-statement if/else
	if (condition) {
		do_this();
		do_that();
	} else {
		otherwise();
	}

switch

	switch (value) {
	case 3:
		printf("three!\n");
		break;
	case 5:
		printf("five!\n");
		break;
	case 42:
		printf("the answer to life, the universe and everything: ");
		// fallthrough
	default:
		printf("%d\n", value);
		break;
	}

Arithmetic

	int a = b * c + 5;

Pointers

	char* some_text = "some text";
	char* just_text = text + 5;
	char t = *just_text;
	char e = just_text[1];

Testing

Unit Tests

wayvnc has a small but growing set of unit tests, which are run on every GitHub PR. To run them locally, do the following:

meson test -C build

Integration Tests

There are also a handful of integration tests which also run on every PR. Read the integration tests documentation for more details, but to run them locally:

./test/integration/integration.sh

Valgrind

There is a helper script in util/valgrind.sh to aid in memory profiling of wayvnc and wayvncctl. This can help find and eliminate memory leaks.

Automated Tests

We run a set of tests on every PR, in three different environments.

Each run ensures that the proposed code change:

1. Builds successfully
2. Passes all unit tests
3. Passes all integration tests

And does so in 3 different environments:

• Ubuntu as a github action
• Arch Linux as a sourcehut build
• FreeBSD as a sourcehut build

No Brown M&Ms

All pull requests must contain the following sentence in the description: I have read and understood CONTRIBUTING.md.