diff --git a/DOCS/contribute.md b/DOCS/contribute.md index 49411033f6..de4022c78a 100644 --- a/DOCS/contribute.md +++ b/DOCS/contribute.md @@ -1,11 +1,62 @@ -Coding style -============ +How to contribute +================= + +General +------- + +The main contact for mpv development is IRC, specifically #mpv-player and +#mpv-player-dev on Freenode. + +Sending patches +--------------- + +- Make a github pull request, or send a link to a plaintext patch created with + ``git format-patch``. diffs posted as pastebins (especially if the http link + returns HTML) just cause extra work for everyone, because they lack commit + message and authorship information. +- Write informative commit messages. Use present tense to describe the + situation with the patch applied, and past tense for the situation before + the change. +- The subject line (the first line in a commit message) should contain a + prefix identifying the sub system, followed by a short description what + impact this commit has. This subject line shouldn't be longer than 72 + characters, because it messes up the output of many git tools otherwise. + + For example, you fixed a crash in af_volume.c: + + Bad: ``fixed the bug (wtf?)`` + Good: ``af_volume: fix crash due to null pointer access`` + + Having a prefix gives context, and is especially useful when trying to find + a specific change by looking at the history, or when running ``git blame``. +- The body of the commit message (everything else after the subject line) should + be as informative as possible and contain everything that isn't obvious. Don't + hesitate to dump as much information as you can - it doesn't cost you + anything. Put some effort into it. If someone finds a bug months or years + later, and finds that it's caused by your commit (even though your commit was + supposed to fix another bug), it would be bad if there wasn't enough + information to test the original bug. The old bug might be reintroduced while + fixing the new bug. + + The commit message should be wrapped on 72 characters per line, because git + tools usually do not break text automatically. On the other hand, you do not + need to break text that would be unnatural to break (like data for test cases, + or long URLs). + + Important: put an empty line between the subject line and the commit message. + If this is missing, it will break display in common git tools. +- Try to separate cosmetic and functional changes. It's ok to make a few + additional cosmetic changes in the same file you're working on. But don't do + something like reformatting a whole file, and hiding an actual functional + change in the same commit. +- If you add a new command line option, document it in options.rst. If you + add a new input property, document it in input.rst. + +Code formatting +--------------- mpv uses C99 with K&R formatting, with some exceptions. -General formatting ------------------- - - Use the K&R indent style. - Use 4 spaces of indentation, never use tabs (except in Makefiles). - Add a single space between keywords and binary operators. There are some other @@ -94,48 +145,3 @@ General coding - If you add features that require intrusive changes, discuss them on the dev channel first. There might be a better way to add a feature and it can avoid wasted work. - -Sending patches ---------------- - -- Make a github pull request, or send a link to a plaintext patch created with - ``git format-patch``. diffs posted as pastebins (especially if the http link - returns HTML) just cause extra work for everyone, because they lack commit - message and authorship information. -- Write informative commit messages. Use present tense to describe the - situation with the patch applied, and past tense for the situation before - the change. -- The subject line (the first line in a commit message) should contain a - prefix identifying the sub system, followed by a short description what - impact this commit has. This subject line shouldn't be longer than 72 - characters, because it messes up the output of many git tools otherwise. - - For example, you fixed a crash in af_volume.c: - - Bad: ``fixed the bug (wtf?)`` - Good: ``af_volume: fix crash due to null pointer access`` - - Having a prefix gives context, and is especially useful when trying to find - a specific change by looking at the history, or when running ``git blame``. -- The body of the commit message (everything else after the subject line) should - be as informative as possible and contain everything that isn't obvious. Don't - hesitate to dump as much information as you can - it doesn't cost you - anything. Put some effort into it. If someone finds a bug months or years - later, and finds that it's caused by your commit (even though your commit was - supposed to fix another bug), it would be bad if there wasn't enough - information to test the original bug. The old bug might be reintroduced while - fixing the new bug. - - The commit message should be wrapped on 72 characters per line, because git - tools usually do not break text automatically. On the other hand, you do not - need to break text that would be unnatural to break (like data for test cases, - or long URLs). - - Important: put an empty line between the subject line and the commit message. - If this is missing, it will break display in common git tools. -- Try to separate cosmetic and functional changes. It's ok to make a few - additional cosmetic changes in the same file you're working on. But don't do - something like reformatting a whole file, and hiding an actual functional - change in the same commit. -- If you add a new command line option, document it in options.rst. If you - add a new input property, document it in input.rst.