opendev/gerrit
Code Issues Proposed changes
6da8b4e824
gerrit/Documentation/user-inline-edit.txt
David Ostrovsky 4b44bdc702 RemoveDrafts: disallow creation of new drafts 
Draft workflow in Gerrit will be deprecated and slated for removal.
This change is the first step in this direction.

However, the repo-tool, mainly used by Andorid developers, is still
depending on drafts and has no support for private or wip changes.
We've added '--private' and '--wip' options to the repo-tool so that
users could have alternatives after pushing drafts is rejected. But,
unfortunately, it has proved hard for us to create a new repo-tool
release containing those two new options. That means we have to find
some workarounds instead of rejecting requests for creating drafts
directly.

The most important feature of drafts is privacy (draft changes and
patch sets are only visible to the change owners and reviewers).
Luckily, we can achieve this with the help of private changes and
change edits:

1- If a user tries to create a draft change, we will create a
private change instead.
2- If a user tries to create a draft patch set, we will create a
change edit instead.

The above behaviors will be a little confusing to our users because
the change or the patch set state is inconsistent with the push
option. But they get almost the same feature. And they can use
similar operations to public their changes/edits. Before this,
they click 'Publish drafts', now they click 'Unmark private' or
'Publish edit'.

After the repo-tool supports private/wip changes, we will reject
those requests with draft option completely.

With this change, users can't create new drafts through the git push
or the 'Create Change' REST API. After this change is released, draft
changes and draft patch sets can still exist in Gerrit sites. The
existing draft changes and draft patch sets can still be published
and deleted. Some operations like cherry-pick may create a new draft
patch set if the current patch set of the target change is draft. But
after migrating existing drafts, there is no way to create a new draft
any more.

Given that Change.Status enum still contains DRAFT value and given that
patch set class still has draft flag, the draft state of changes and
patch sets can still be toggled programmatically. Thus we can keep most
drafts related unit tests until existing draft changes and draft patch
sets are migrated to non-draft changes and patch sets.

Migration path for draft changes and patch sets (will be done in
follow-up changes):

* Draft changes will be migrated to private or work-in-progress changes
* Draft patch sets will be published

During this migration, the DRAFT value will be removed from the
Change.Status enum and the draft flag will be removed from the patch set
class.

Bug: Issue 6881
Change-Id: I8663f0580b90d7ce10a597b42abecf8734d3f9b2
2017-09-15 07:50:36 +02:00

192 lines
7.4 KiB
Plaintext
Raw Blame History

= Inline Edit
This page explains the workflow for creating and amending changes in the
browser.
[[create-change]]
== Creating a New Change
A new change can be created directly in the browser, meaning it is not necessary
to clone the whole repository to make trivial changes.
The new change is created as a public
link:user-upload.html#wip[work-in-progress change].
There are two different ways to create a new change:
By clicking on the 'Create Change' button in the project screen:
[[create-change-from-project-info-screen]]
image::images/inline-edit-create-change-project-screen.png[width=800, link="images/inline-edit-create-change-project-screen.png"]
The user can select the branch on which the new change should be created:
image::images/inline-edit-create-change-project-screen-dialog.png[width=800, link="images/inline-edit-create-change-project-screen-dialog.png"]
By clicking the 'Follow-Up' button on the change screen, to create a new change
based on the selected change.
[[create-change-from-change-screen]]
image::images/inline-edit-create-follow-up-change.png[width=800, link="images/inline-edit-create-follow-up-change.png"]
[[editing-change]]
== Editing Changes
To switch to edit mode, press the 'Edit' button at the top of the file list:
[[switch-to-edit-mode]]
image::images/inline-edit-enter-edit-mode-from-file-list.png[width=800, link="images/inline-edit-enter-edit-mode-from-file-list.png"]
While in edit mode, it is possible to add new files to the change by clicking
the 'Add...' button at the top of the file list.
File changes can be reverted or files can be removed from the change or
deleted files can be restored, by clicking the icons to the left of the file
name.
To switch from edit mode back to review mode, click the 'Done Editing' button.
image::images/inline-edit-file-list-in-edit-mode.png[width=800, link="images/inline-edit-file-list-in-edit-mode.png"]
[[open-full-screen-editor]]
While in edit mode, clicking on a file name in the file list opens a full
screen editor for that file.
To save edits, click the 'Save' button or press `CTRL-S`. To return to the
change screen, click the 'Close' button.
Note that when editing the commit message, trailing blank lines will be stripped.
image::images/inline-edit-full-screen-editor.png[width=800, link="images/inline-edit-full-screen-editor.png"]
If there are unsaved edits when the 'Close' button is pressed, a dialog will
pop up asking to confirm the edits.
image::images/inline-edit-confirm-unsaved-edits.png[width=800, link="images/inline-edit-confirm-unsaved-edits.png"]
To discard the unsaved edits and return to the change screen, click the 'OK'
button. To continue editing, click 'Cancel'.
[[switch-to-edit-mode-from-side-by-side]]
While in review mode, it is possible to switch directly to edit mode and into an
editor for a file under review by clicking on the edit icon in the patch set list
on the side-by-side diff view.
image::images/inline-edit-enter-edit-mode-from-diff.png[width=800, link="images/inline-edit-enter-edit-mode-from-diff.png"]
[[reviewing-changes-made-in-change-edit]]
== Reviewing Change Edits
Change edits are reviewed in the same way as regular patch sets, using the
side-by-side diff screen. Change edits are shown as 'edit' in the patch list
on the diff screen:
image::images/inline-edit-edit-in-diff-screen-patch-list.png[width=800, link="images/inline-edit-edit-in-diff-screen-patch-list.png"]
and on the change screen:
image::images/inline-edit-edit-in-patch-list.png[width=800, link="images/inline-edit-edit-in-patch-list.png"]
Note that patch sets may exist that were created after the change edit was created.
For example this sequence:
`1 2 3 4 5 6 7 8 9 edit 10`
means that the change edit was created on top of patch set number 9 and a regular
patch set was uploaded later.
[[change-edit-actions]]
== Change Edit Actions
Change edits can be deleted, published and rebased, and a patch set that
represents a change edit can be downloaded like a regular patch set.
[[delete-change-edit]]
There is a special ref for a change edit. When the change edit is deleted, this
ref is deleted as well. To delete a change edit click on the "Delete Edit"
button.
[[publish-change-edit]]
When a change edit is based on the current patch set, it can be published. By
publishing a change edit it is promoted to a regular patch set. The special ref
that represents the change edit is deleted on publish. To publish a change edit
click on the "Publish Edit" button. This button is only shown when the change
edit is based on the current patch set. Otherwise the change edit must first be
rebased onto the current patch set.
[[rebase-change-edit]]
Only change edits that are based on the current patch set can be published. If
in the meantime a new patch set was uploaded, the change edit must be rebased on
top of the current patch set before it can be published. Rebasing a change
edit is done by clicking on the "Rebase Edit" button. If the rebase results in
conflicts, these conflicts cannot be resolved in the browser. In this case the
change edit must be downloaded (see below) and the conflicts must be resolved in
the local environment. The commit that contains the conflict resolution can then
be uploaded by setting `edit` as option on the target ref:
----
$ git push host HEAD:refs/for/master%edit
----
[[download-change-edit-patch]]
Like regular patch sets, change edits can be downloaded by the download
commands (e.g. provided by the `download-commands` plugin). To download a
change edit, select the desired scheme from the "Download" dropdown and copy the
command to your terminal. Note: only change edit owners and users that were
granted the link:access-control.html#capability_accessDatabase[accessDatabase]
global capability are able to access change edit refs.
[[search-for-change-edits]]
To search change edits from the UI the link:user-search.html#has[has:edit]
predicate can be used.
Alternatively change edits can be accessed through "My => Edits" dashboard.
[[not-implemented-features]]
== Not Implemented Features
* Support default configuration options for inline editor that an
administrator has set in `refs/users/default:preferences.config` file.
* Allow to rename files that are already contained in the change (from the file table).
The same rename file dialog can be used with preselected and disabled original file
name.
* Changed files in change edit should be marked as changed in file table in edit mode.
One option is to use dirty icon or "*" char in front of changed files, another option
is to use different hyperlink color for changed files (red?), to avoid adding yet another
column to the file table
* Add navigation icons in header area of edit screen. When dozen files need to be changed
in context of change edit, this is not the best workflow to open one file in edit screen,
change it, save it, close edit screen and select next file from the file table to edit.
"<-" | "->" icons in header of edit screen could be used to navigate to the next file to
change from the file table. This would behave like the navigation icons in side by side
with the following logic on click:
** "save-when-file-was-changed" or
** "close-when-no-changes"
* Implement conflict resolution during rebase of change edit using inline edit
feature by creating new edit on top of current patch set with auto merge content
* Similarly, reuse inline edit feature for conflict resolution during rebase of regular
patch sets
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------
View Git Blame Copy Permalink