Discussion API, "Create new merge request thread" is underdocumented
Sufficiently document the "Create new merge request thread" request type of the Discussion API
As for now its documentation (https://docs.gitlab.com/ee/api/discussions.html#create-new-merge-request-thread) lacks some information crucial for its usage and missing pieces are not easy to guess (and are, to some extent, counter-intuitive).
Note: it is quite likely that some other request types from this API suffer from the same problem
Further details
It isn't specified, which combinations of position[new_path], position[old_path], position[new_line], position[old_line] attributes have to be provided in an request and to which values these attributes have to be set in following cases
- added file,
- deleted file,
- renamed file,
- added line,
- deleted line,
- unchanged line. Note, that settings required by this call are rather counter-intuitive and differ from what you may expect looking on an output of the standard git diff for these cases.
For example (position[] in attribute names is omitted for a sake of brevity):
- for the newly added file you have to specify both new_path and old_path and set both of them to a path of the added file (while git diff shows old path as /dev/null, see below)
>git diff HEAD^
diff --git a/added_file.txt b/added_file.txt
new file mode 100644
index 0000000..6dc0bf5
--- /dev/null
+++ b/added_file.txt
@@ -0,0 +1 @@
-
for the deleted file it is essentially the same - you have to specify both new_path and old_path and to set both of them to the path of the file before deletion.
-
for the added (modified) line you have to set new_line, but must omit old_line (this approach is reasonable, but inconsistent with an approach to new_path / old_path for the added file).
-
for deleted line you must to omit new_line and have to specify old_line ((this approach is reasonable, but inconsistent with an approach to new_path / old_path for the deleted file).
-
for unchanged line you must to specify both old_line and new_line - while any of them uniquely identify another and so it isn't obvious that both to be specified.
Reactions on incorrect parameter values/combinations are not documented (and, as for now, they are inconsistent - a separate ticket will be created).
The documentation doesn't mention that abbreviated SHA-s aren't fully supported - while a comment is created exactly as in a case of full SHA-s it is not shown inline on the Changes tab of the merger request see sha-demo.bat, sha-demo.json, glapi-testbed.git.tgz and this screenshot
Proposal
Add this info to documentation (unless behavior would be fixed - a separate ticket will be created for it).
Who can address the issue
Other links/references
Support request https://support.gitlab.com/hc/en-us/requests/138005 contains information about this issue as well as interrelated deficiencies of Discussions API.