doc&tools: Add murge script, for analyzing 3 way conflicts.
[ffmpeg.git] / doc / libav-merge.txt
1 CONTEXT
2 =======
3
4 The FFmpeg project merges all the changes from the Libav project
5 (https://libav.org) since the origin of the fork (around 2011).
6
7 With the exceptions of some commits due to technical/political disagreements or
8 issues, the changes are merged on a more or less regular schedule (daily for
9 years thanks to Michael, but more sparse nowadays).
10
11 WHY
12 ===
13
14 The majority of the active developers believe the project needs to keep this
15 policy for various reasons.
16
17 The most important one is that we don't want our users to have to choose
18 between two distributors of libraries of the exact same name in order to have a
19 different set of features and bugfixes. By taking the responsibility of
20 unifying the two codebases, we allow users to benefit from the changes from the
21 two teams.
22
23 Today, FFmpeg has a much larger user database (we are distributed by every
24 major distribution), so we consider this mission a priority.
25
26 A different approach to the merge could have been to pick the changes we are
27 interested in and drop most of the cosmetics and other less important changes.
28 Unfortunately, this makes the following picks much harder, especially since the
29 Libav project is involved in various deep API changes. As a result, we decide
30 to virtually take everything done there.
31
32 Any Libav developer is of course welcome anytime to contribute directly to the
33 FFmpeg tree. Of course, we fully understand and are forced to accept that very
34 few Libav developers are interested in doing so, but we still want to recognize
35 their work. This leads us to create merge commits for every single one from
36 Libav. The original commit appears totally unchanged with full authorship in
37 our history (and the conflict are solved in the merge one). That way, not a
38 single thing from Libav will be lost in the future in case some reunification
39 happens, or that project disappears one way or another.
40
41 DOWNSIDES
42 =========
43
44 Of course, there are many downsides to this approach.
45
46 - It causes a non negligible merge commits pollution. We make sure there are
47   not several level of merges entangled (we do a 1:1 merge/commit), but it's
48   still a non-linear history.
49
50 - Many duplicated work. For instance, we added libavresample in our tree to
51   keep compatibility with Libav when our libswresample was already covering the
52   exact same purpose. The same thing happened for various elements such as the
53   ProRes support (but differences in features, bugs, licenses, ...). There are
54   many work to do to unify them, and any help is very much welcome.
55
56 - So much manpower from both FFmpeg and Libav is lost because of this mess. We
57   know it, and we don't know how to fix it. It takes incredible time to do
58   these merges, so we have even less time to work on things we personally care
59   about. The bad vibes also do not help with keeping our developers motivated.
60
61 - There is a growing technical risk factor with the merges due to the codebase
62   differing more and more.
63
64 MERGE GUIDELINES
65 ================
66
67 The following gives developer guidelines on how to proceed when merging Libav commits.
68
69 Before starting, you can reduce the risk of errors on merge conflicts by using
70 a different merge conflict style:
71
72     $ git config --global merge.conflictstyle diff3
73
74 Here is a script to help merging the next commit in the queue:
75
76     #!/bin/sh
77
78     if [ "$1" != "merge" -a "$1" != "noop" ]; then
79        printf "Usage: $0 <merge|noop [REF_HASH]>\n"
80        exit 0
81     fi
82
83     [ "$1" = "noop" ] && merge_opts="-s ours"
84
85     nextrev=$(git rev-list libav/master --not master --no-merges | tail -n1)
86     if [ -z "$nextrev" ]; then
87         printf "Nothing to merge..\n"
88         exit 0
89     fi
90     printf "Merging $(git log -n 1 --oneline $nextrev)\n"
91     git merge --no-commit $merge_opts --no-ff --log $nextrev
92
93     if [ "$1" = "noop" -a -n "$2" ]; then
94        printf "\nThis commit is a noop, see $2\n" >> .git/MERGE_MSG
95     fi
96
97     printf "\nMerged-by: $(git config --get user.name) <$(git config --get user.email)>\n" >> .git/MERGE_MSG
98
99
100 The script assumes a remote named libav.
101
102 It has two modes: merge, and noop. The noop mode creates a merge with no change
103 to the HEAD. You can pass a hash as extra argument to reference a justification
104 (it is common that we already have the change done in FFmpeg).
105
106 Also see tools/murge, you can copy and paste a 3 way conflict into its stdin
107 and it will display colored diffs. Any arguments to murge (like ones to suppress
108 whitespace differences) are passed into colordiff.
109
110 TODO/FIXME/UNMERGED
111 ===================
112
113 - HEVC DSP and x86 MC SIMD improvements from Libav (see http://comments.gmane.org/gmane.comp.video.ffmpeg.devel/204917)
114 - Porting ffmpeg*.c to codecpar (see bbf5ef9dac9475d8ed22da23acc2eb63a2640784)