tests/org.eclipse.team.tests.cvs.core/html/validate_edit_editing_files00001.html - gerrit/platform/eclipse.platform.team - Git at Google

 <html>
 <head>
 <title>Editing Files</title>
 <LINK REL=STYLESHEET HREF=../book.css CHARSET=ISO-8859-1 TYPE=text/css>
 <meta NAME="keywords" content="">
 <meta NAME="since" content="">
 </head>
 <body>
 <h2>Editing Files</h2>
 <p>Since: <br>
 Last Modified: $Date: 2007/05/18 13:54:37 $</p>

 <p>These tests are to sanity check editors behavior relating to
 calling validateEdit. The tests will try to cover all cases where files
 are changed by the validateEdit handler and changes are made to the
 read-only bit.</p>

 <p>These test cases outline the expected behavior of single file
 editors in terms of calling validateEdit and handling of error
 conditions. All scenarios assume that a repository provider is mapped to
 a project and has created a sandbox with files that are marked
 read-only.</p>

 <p>The <a
 	href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.examples.filesystem/">
 org.eclipse.team.example.filesystem</a> plugin is a repository provider that
 simulates a pessimistic workflow. You can use it to run these tests and
 validate (no pun intended) your validateEdit editor support. To use the
 pessimistic provider, share a project with the repository provider
 called "File System Pessimistic Example" and then you can add to control
 the files and checkin/checkout will toggle the read-only bit and touch
 the file. You can change the behavior of the validateEdit call via the
 pessimistic preference page. For example, you can force the operation to
 fail and update contents of the file when checked out.</p>

 <p>These tests should be run against the following combinations of
 tools:</p>

 <ul>
 	<li>Different repository providers</li>
 	<li>Single file editors (java, text)</li>
 	<li>Multiple file editors (manifest editor, ...)</li>
 </ul>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S1: Repository provider enabled and files are readable</h3>
 <ol>
 	<li>Open a file that is not marked read-only in a project
 	configured with a repository provider.</li>
 	<li>Start editing the file, validate edit should not be called.</li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S2: Validate edit called on first edit</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Start editing the file, validateEdit should be called.</li>
 	<li>validateEdit returns OK, the users edit is accepted and shows
 	up in the editor, and the file can be edited normally.</li>
 	<li>The user saves the file, and then can continue editing without
 	validateEdit being called.</li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S2b: Validate edit canceled</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Start editing the file, validateEdit should be called.</li>
 	<li>validateEdit is canceled, the users edit is not accepted and
 	the file cannot be edited.</li>
 	<li>The user should still be able to browse the contents of the
 	file and trying to edit it again</li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S2b: Validate edit fails with an error</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Start editing the file, validateEdit should be called.</li>
 	<li>validateEdit is canceled, the users edit is not accepted and
 	the file cannot be edited. User should be shown the error returned from
 	the validateEdit provider.</li>
 	<li>The user should still be able to browse the contents of the
 	file and trying to edit it again</li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S3: Validate edit called on subsequent edits if file changes
 state</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Start editing the file, validateEdit should be called.</li>
 	<li>validateEdit returns OK, the user's edit is accepted and the
 	file can be edited normally.</li>
 	<li>The user saves the file, and then can continue editing without
 	validateEdit being called.</li>
 	<li>The user saves the file and then checks in the file while the
 	editor is still open.</li>
 	<li>After the checkin completes the user continues editing the
 	file.</li>
 	<li>Validate edit should be called again.</li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S4: Validate edit not called after contents changed</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Start editing the file, validateEdit should be called.</li>
 	<li>validateEdit returns OK, the user's edit is accepted and the
 	file can be edited normally.</li>
 	<li>The user saves the file, and then can continue editing without
 	validateEdit being called.</li>
 	<li>The user saves the file and keeps the editor opened.</li>
 	<li>The user then un-checks out the file and new file contents are
 	retrieved from the server.</li>
 	<li>The new file contents are loaded into the editor and
 	validateEdit is not called.</li>
 	<li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S5: Validate edit changes file contents editor not-dirty</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Start editing the file, validateEdit should be called.</li>
 	<li>validateEdit returns OK and brings in new content from the
 	server.</li>
 	<li>The new content is loaded automatically because the editor
 	isn't dirty yet.</li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S6: Validate edit changes file contents editor dirty</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Start editing the file, validateEdit should be called.</li>
 	<li>validateEdit returns OK and the file on disk doesn't change.</li>
 	<li>The user continues editing the file and then checks it in.</li>
 	<li>The editor remains open and dirty, the user continues editing.</li>

 	<li>validateEdit is called because the file is now read-only and
 	returns OK and brings in new content from the server.</li>
 	<li>The editor detects the timestamp change and prompts about the
 	conflict and provides <a href="#reload_options">options</a> to the
 	user.</li>
 	<li>After the user selects his option and the user continues
 	editing, the editor will call validateEdit.</li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S7: Read-only editors refreshing on checkout</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Checkout the file that brings in new content from the server.</li>
 	<li>The editor should update with the new content from the server.</li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S8: validate called on editor save</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Start editing the file, validateEdit should be called.</li>
 	<li>validateEdit returns OK and the file on disk doesn't change.</li>
 	<li>The editor remains open and dirty, the user continues editing.</li>
 	<li>The user checks-n the file and then closes the editor.</li>
 	<li>The user is prompted to save the file, then validate edit is
 	called, and the file is checked-out then saved.</li>
 </ol>

 <!-- ------------------------------------------------------------------------------ -->

 <h3>S9: validate called on editor save with new contents</h3>
 <ol>
 	<li>Open a file that has been checked out as read-only from a
 	repository provider.</li>
 	<li>Start editing the file, validateEdit should be called.</li>
 	<li>validateEdit returns OK and the file on disk doesn't change.</li>
 	<li>The editor remains open and dirty, the user continues editing.</li>
 	<li>The user checks-n the file and then closes the editor.</li>
 	<li>The user is prompted to save the file, then validate edit is
 	called, and the file is checked-out then saved.</li>
 </ol>

 <!--
 <hr>

 <a name="reload_options"><h3>Conflict Resolution Options for Editors</h3>
 <pre>
 Assumptions:
     1. Editors currently maintain a "dirty bit" indicating that the in-memory
        buffer has been modified and not yet written to disk.  Editors call
        validateEdit() the if the file is read-only and the dirty bit is going
        from the clean state to the dirty state.
     2. Editors can detect when the timestamp of the file has changed on disk
        and prompt the user for the appropriate action.

 Suggestion:
     Editors should maintain a separate bit, "must call validateEdit()".  Any
     modification of the buffer calls validateEdit() first if this bit is set.
     It is initially set when the file is opened if the file is read-only.  It
     is cleared after a successful call to validateEdit().  It is set again
     when the editor notices that a file has gone from read/write to read-only.

     If the "must call validateEdit()" bit ever goes from the cleared state to
     the set state (except for when the file is initially opened), a later
     successful call to validateEdit(), should should result in the following
     actions:

     +-----------+------------------+----------------------------------------+
     | Dirty Bit | Timestamp Change | Editor Action                          |
     |   State   |     Detected     |                                        |
     +-----------+------------------+----------------------------------------+
     |     0     |        no        | No action required                     |
     +-----------+------------------+----------------------------------------+
     |     1     |        no        | No action required                     |
     +-----------+------------------+----------------------------------------+
     |     0     |        yes       | Prompt user for reload/no-reload/merge |
     +-----------+------------------+----------------------------------------+
     |     1     |        yes       | Prompt user for reload/no-reload/merge |
     +-----------+------------------+----------------------------------------+
 </pre>
 -->

 </body>
 </html>
	<html>
	<head>
	<title>Editing Files</title>
	<LINK REL=STYLESHEET HREF=../book.css CHARSET=ISO-8859-1 TYPE=text/css>
	<meta NAME="keywords" content="">
	<meta NAME="since" content="">
	</head>
	<body>
	<h2>Editing Files</h2>
	<p>Since: <br>
	Last Modified: $Date: 2007/05/18 13:54:37 $</p>

	<p>These tests are to sanity check editors behavior relating to
	calling validateEdit. The tests will try to cover all cases where files
	are changed by the validateEdit handler and changes are made to the
	read-only bit.</p>

	<p>These test cases outline the expected behavior of single file
	editors in terms of calling validateEdit and handling of error
	conditions. All scenarios assume that a repository provider is mapped to
	a project and has created a sandbox with files that are marked
	read-only.</p>

	<p>The <a
	href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.examples.filesystem/">
	org.eclipse.team.example.filesystem</a> plugin is a repository provider that
	simulates a pessimistic workflow. You can use it to run these tests and
	validate (no pun intended) your validateEdit editor support. To use the
	pessimistic provider, share a project with the repository provider
	called "File System Pessimistic Example" and then you can add to control
	the files and checkin/checkout will toggle the read-only bit and touch
	the file. You can change the behavior of the validateEdit call via the
	pessimistic preference page. For example, you can force the operation to
	fail and update contents of the file when checked out.</p>

	<p>These tests should be run against the following combinations of
	tools:</p>

	<ul>
	<li>Different repository providers</li>
	<li>Single file editors (java, text)</li>
	<li>Multiple file editors (manifest editor, ...)</li>
	</ul>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S1: Repository provider enabled and files are readable</h3>
	<ol>
	<li>Open a file that is not marked read-only in a project
	configured with a repository provider.</li>
	<li>Start editing the file, validate edit should not be called.</li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S2: Validate edit called on first edit</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Start editing the file, validateEdit should be called.</li>
	<li>validateEdit returns OK, the users edit is accepted and shows
	up in the editor, and the file can be edited normally.</li>
	<li>The user saves the file, and then can continue editing without
	validateEdit being called.</li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S2b: Validate edit canceled</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Start editing the file, validateEdit should be called.</li>
	<li>validateEdit is canceled, the users edit is not accepted and
	the file cannot be edited.</li>
	<li>The user should still be able to browse the contents of the
	file and trying to edit it again</li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S2b: Validate edit fails with an error</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Start editing the file, validateEdit should be called.</li>
	<li>validateEdit is canceled, the users edit is not accepted and
	the file cannot be edited. User should be shown the error returned from
	the validateEdit provider.</li>
	<li>The user should still be able to browse the contents of the
	file and trying to edit it again</li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S3: Validate edit called on subsequent edits if file changes
	state</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Start editing the file, validateEdit should be called.</li>
	<li>validateEdit returns OK, the user's edit is accepted and the
	file can be edited normally.</li>
	<li>The user saves the file, and then can continue editing without
	validateEdit being called.</li>
	<li>The user saves the file and then checks in the file while the
	editor is still open.</li>
	<li>After the checkin completes the user continues editing the
	file.</li>
	<li>Validate edit should be called again.</li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S4: Validate edit not called after contents changed</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Start editing the file, validateEdit should be called.</li>
	<li>validateEdit returns OK, the user's edit is accepted and the
	file can be edited normally.</li>
	<li>The user saves the file, and then can continue editing without
	validateEdit being called.</li>
	<li>The user saves the file and keeps the editor opened.</li>
	<li>The user then un-checks out the file and new file contents are
	retrieved from the server.</li>
	<li>The new file contents are loaded into the editor and
	validateEdit is not called.</li>
	<li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S5: Validate edit changes file contents editor not-dirty</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Start editing the file, validateEdit should be called.</li>
	<li>validateEdit returns OK and brings in new content from the
	server.</li>
	<li>The new content is loaded automatically because the editor
	isn't dirty yet.</li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S6: Validate edit changes file contents editor dirty</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Start editing the file, validateEdit should be called.</li>
	<li>validateEdit returns OK and the file on disk doesn't change.</li>
	<li>The user continues editing the file and then checks it in.</li>
	<li>The editor remains open and dirty, the user continues editing.</li>

	<li>validateEdit is called because the file is now read-only and
	returns OK and brings in new content from the server.</li>
	<li>The editor detects the timestamp change and prompts about the
	conflict and provides <a href="#reload_options">options</a> to the
	user.</li>
	<li>After the user selects his option and the user continues
	editing, the editor will call validateEdit.</li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S7: Read-only editors refreshing on checkout</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Checkout the file that brings in new content from the server.</li>
	<li>The editor should update with the new content from the server.</li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S8: validate called on editor save</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Start editing the file, validateEdit should be called.</li>
	<li>validateEdit returns OK and the file on disk doesn't change.</li>
	<li>The editor remains open and dirty, the user continues editing.</li>
	<li>The user checks-n the file and then closes the editor.</li>
	<li>The user is prompted to save the file, then validate edit is
	called, and the file is checked-out then saved.</li>
	</ol>

	<!-- ------------------------------------------------------------------------------ -->

	<h3>S9: validate called on editor save with new contents</h3>
	<ol>
	<li>Open a file that has been checked out as read-only from a
	repository provider.</li>
	<li>Start editing the file, validateEdit should be called.</li>
	<li>validateEdit returns OK and the file on disk doesn't change.</li>
	<li>The editor remains open and dirty, the user continues editing.</li>
	<li>The user checks-n the file and then closes the editor.</li>
	<li>The user is prompted to save the file, then validate edit is
	called, and the file is checked-out then saved.</li>
	</ol>

	<!--
	<hr>

	<a name="reload_options"><h3>Conflict Resolution Options for Editors</h3>
	<pre>
	Assumptions:
	1. Editors currently maintain a "dirty bit" indicating that the in-memory
	buffer has been modified and not yet written to disk. Editors call
	validateEdit() the if the file is read-only and the dirty bit is going
	from the clean state to the dirty state.
	2. Editors can detect when the timestamp of the file has changed on disk
	and prompt the user for the appropriate action.

	Suggestion:
	Editors should maintain a separate bit, "must call validateEdit()". Any
	modification of the buffer calls validateEdit() first if this bit is set.
	It is initially set when the file is opened if the file is read-only. It
	is cleared after a successful call to validateEdit(). It is set again
	when the editor notices that a file has gone from read/write to read-only.

	If the "must call validateEdit()" bit ever goes from the cleared state to
	the set state (except for when the file is initially opened), a later
	successful call to validateEdit(), should should result in the following
	actions:

	+-----------+------------------+----------------------------------------+
	\| Dirty Bit \| Timestamp Change \| Editor Action \|
	\| State \| Detected \| \|
	+-----------+------------------+----------------------------------------+
	\| 0 \| no \| No action required \|
	+-----------+------------------+----------------------------------------+
	\| 1 \| no \| No action required \|
	+-----------+------------------+----------------------------------------+
	\| 0 \| yes \| Prompt user for reload/no-reload/merge \|
	+-----------+------------------+----------------------------------------+
	\| 1 \| yes \| Prompt user for reload/no-reload/merge \|
	+-----------+------------------+----------------------------------------+
	</pre>
	-->

	</body>
	</html>