Add KNOWN-ISSUES.md file

Add KNOWN-ISSUES.md file with the description of a git-upstream known
bug.

AUTHORS

@@ -0,0 +1,8 @@
+Darragh Bailey <dbailey@hp.com>
+Davide Guerri <davide.guerri@hp.com>
+Jon-Paul Sullivan <jonpaul.sullivan@hp.com>
+Monty Taylor <mordred@inaugust.com>
+
+This list has been extracted with:
+
+git log --format='%aN <%aE>' | grep -v Jenkins | sort -u

DESCRIPTION

@@ -8,3 +8,5 @@ patches on top of upstream repositories. It provides commands to ease the use of
 git for who needs to integrate big upstream projects in their environment (i.e.,
 feature branch creation/finishing, release starting/finishing).
 The operations are performed using Git commands.
+
+See also README.md, USAGE.md and KNOWN-ISSUES.md files.

KNOWN-ISSUES.md

@@ -0,0 +1,44 @@
+# git-upstream import could miss some local changes
+
+## Problem description
+
+If previous local changes were based off of a point before the previous import merge was complete, and were not rebased to be applied after this point before being merged, the import command will miss including these when discarding previous obsolete history.
+
+Given a previous import like the following where previously changes B & C were replayed, and the import was merged as E. Where subsequently a change D which was proposed before the import, is merged to mainline, a subsequent run of the tool to import K will fail to include D along with B', C' & G' when discarding the assumed unnecessary merges E & F. While these should be discarded, the tool needs to check to make sure if there are dangling changes that should be included.
+
+              D----
+             /     \
+         B---C---E---F---L  mainline
+        /       /
+       /   B'--C'           import/G
+      /   /
+     A---G---H---I---J---K  upstream
+
+
+
+The tool will find the following commit path to consider:
+
+                 E---F---L
+                /
+           B'--C'
+          /
+         G
+
+## Implementing a fix (WiP)
+
+With respect to the previous diagrams, the correct behaviour is to find the following set:
+
+               D----
+                    \
+                 E---F---L
+                /
+           B'--C'
+          /
+         G
+
+This requires walking the list of initial found (2nd diagram) and examining each merge commit up to the previous import to see if there is a change that shares history with the other parent. i.e. look at F and see if D contains a merge-base in common with E, an thus include. Or locate E and find any differences between E & L that should be included.
+
+## Workaround
+
+Waiting for a proper fix to be implemented, a workaround for this issue would be to perform the import only into a branch (usually master) which has no "pending" commit in other branches to be merged.
+For gerrit this means not having pending reviews spanning across different git-upstream import command runs.

README.md

@@ -176,6 +176,9 @@ To show a specific note run `git notes --ref refs/notes/upstream-merge show <mar
 As `supersede` uses git notes to mark commits that have to be skipped during import, notes should be present on the cloned copy of your repository. Thus, if you are going to create notes on a system and perform the actual import on a different system, **notes must be present on the latter**.
 You can push notes directly to git repository on the target system or push them in a different repository and then pull notes from your target system.
 
+# Known issues
+
+Please see `KNOWN-ISSUES.md`.
 
 # Authors
 git-upstream was written by Darragh Bailey <dbailey@hp.com>.