summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2014-06-17 23:15:25 +0200
committerwm4 <wm4@nowhere>2014-06-17 23:18:13 +0200
commit2827ff1eabbe87f7f91ae174ba321cab06f5cbe0 (patch)
tree505d6d82300e7ae4fd8f46994b5c32e8179f7cdc
parented1250b0806dca8c67683f74a6f93348dede0a27 (diff)
downloadmpv-2827ff1eabbe87f7f91ae174ba321cab06f5cbe0.tar.bz2
mpv-2827ff1eabbe87f7f91ae174ba321cab06f5cbe0.tar.xz
DOCS/contribute.md: move instructions for sending patches to the top
Separate to not confuse git history tracking.
-rw-r--r--DOCS/contribute.md106
1 files changed, 56 insertions, 50 deletions
diff --git a/DOCS/contribute.md b/DOCS/contribute.md
index 49411033f6..de4022c78a 100644
--- a/DOCS/contribute.md
+++ b/DOCS/contribute.md
@@ -1,10 +1,61 @@
-Coding style
-============
+How to contribute
+=================
-mpv uses C99 with K&R formatting, with some exceptions.
+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.
-General formatting
-------------------
+Code formatting
+---------------
+
+mpv uses C99 with K&R formatting, with some exceptions.
- Use the K&R indent style.
- Use 4 spaces of indentation, never use tabs (except in Makefiles).
@@ -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.