mirror of
https://github.com/mpv-player/mpv
synced 2025-02-16 12:17:12 +00:00
DOCS/contribute.md: move instructions for sending patches to the top
Separate to not confuse git history tracking.
This commit is contained in:
parent
ed1250b080
commit
2827ff1eab
@ -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.
|
mpv uses C99 with K&R formatting, with some exceptions.
|
||||||
|
|
||||||
General formatting
|
|
||||||
------------------
|
|
||||||
|
|
||||||
- Use the K&R indent style.
|
- Use the K&R indent style.
|
||||||
- Use 4 spaces of indentation, never use tabs (except in Makefiles).
|
- Use 4 spaces of indentation, never use tabs (except in Makefiles).
|
||||||
- Add a single space between keywords and binary operators. There are some other
|
- 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
|
- 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
|
channel first. There might be a better way to add a feature and it can avoid
|
||||||
wasted work.
|
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.
|
|
||||||
|
Loading…
Reference in New Issue
Block a user