How To Create Patch For Stendhal
- |
If you want to contribute to Stendhal with some changes to some files you can ease us integrating the changes if you create a patch file for your changes.
A patch file is a record of all the changes made to the code. It is one file in a particular format which defines which source files, and which lines of the source files are to be changed, as well as the changes themself. As you can imagine this makes adding changes a much smoother process.
There are a few neat ways to make a patch file. We are going to describe here how to create a patch on each of this ways.
Once you have tested your patch please add it to our sourceforge tracker.
As a prerequisite for both ways of creating a patch is a checked out version of Stendhal.
Common best practices for patches and CVS
- Keep your local copy of Stendhal regularly up to date with CVS Head to avoid merge conflicts
- Discuss your plans with the team at #arianne
- Update your local copy before you test your changes locally
- Test your changes locally
- Open the patch file in a text editor and review it, to check it is really adding the changes you mean to add, and nothing else
Creating patches
Eclipse
If you use Eclipse it is quite easy for you to create a patch against current head version in CVS. Before creating a patch you should update your local copy of the sources to the most recent version. You do this by right clicking on the project folder, and in the context menu which appears select Team and Update. If files have been edited outside Eclipse, please right click on the project folder and click Refresh.
After updating your Stendhal project you can start the patch creation by right clicking on the project. In the context menu which appears select Team and Create Patch in the team submenu. This will open up a wizard for creating patches.
The first wizard page asks you where to create the patch. For submitting a patch to our patches tracker you should choose file as selected in the next screenshot. For creating a patch file you also have to select a file name and location for the patch. You can easily select a target folder and file name by clicking on Browse. The last thing you have to choose on this windows are the changes. If you want to bring all current differences to CVS into the patch file just tick the root node of the shown project tree in the Changes area of the window.
In the next step which is also the final step you need to specify two other options. Just select the options as shown in the screenshot and click on Finish.
After clicking on finish you will not get any further notice but the patch file should now be available in the previously selected folder.
Command line
In your stendhal code development folder type:
cvs diff -uN > descriptive_name.patch
If you have unversioned (new!) files to include in your patch, you will notice that the above command simply adds the file's name to the top of your patch, prefixed with a question mark. You can check this by opening the patch file in any text editor. This is because your new file is not tagged for adding to the repository. Just do
cvs add newfile
or for a binary file like an image or tmx map file
cvs add -kb newbinaryfile
TODO: Verify this is possible with anon access ?
Then
cvs diff -uNa > descriptive_name.patch
This should add the correct code to the patch, so that someone applying the patch to their working copy will have a new file created at the right place (hopefully!).
If your patch, for some reason (like you being on Windows), contains a lot of white space changes in many files, you might want to add -Bbw to the diff call. This can make a patch a lot smaller, and thus easier to review. The complete call would then be
cvs diff -uNawbB > descriptive_name.patch
Tortoise CVS
Tortoise CVS is a Windows GUI front end for CVS. So, if you are using Tortoise CVS already, you can create a patch. Right-click on the stendhal code development folder in CVS, and choose CVS -> Make patch ... from the context menu.
Reading patch files
Eek, what is all this text below?
The patch file contains a section for each file that should be changed. That section starts with lines that contain the file name and path of first the old (---) and then the new (+++) version and some additional information.
Then follow sets of changes. They start with a line that contains, enclosed in @@, the line or line range from,no-of-lines in the file before (with a -) and after (with a +) the changes. After that come the lines from the file. Lines starting with a - are deleted, lines starting with a + are added. Each line modified by the patch is surrounded with 3 lines of context before and after. A line change needs both an addition + and a deletion -.
After all the changes related to one file, comes the next file definitions (--- and +++) and the next file's changes, with the @@ and + or - as above.
Index: src/games/stendhal/client/gui/j2d/entity/RPEntity2DView.java
===================================================================
RCS file: /cvsroot/arianne/stendhal/src/games/stendhal/client/gui/j2d/entity/RPEntity2DView.java,v
retrieving revision 1.40
diff -u -r1.40 RPEntity2DView.java
--- src/games/stendhal/client/gui/j2d/entity/RPEntity2DView.java 24 Oct 2009 22:11:04 -0000 1.40
+++ src/games/stendhal/client/gui/j2d/entity/RPEntity2DView.java 20 Nov 2009 23:50:47 -0000
@@ -19,6 +19,7 @@
import games.stendhal.client.sprite.AnimatedSprite;
import games.stendhal.client.sprite.Sprite;
import games.stendhal.client.sprite.SpriteStore;
+import games.stendhal.common.Debug;
import games.stendhal.common.Direction;
import java.awt.Color;
@@ -602,8 +603,7 @@
drawIdeas(g2d, x, y, height);
}
- // Enable this to debug entity view area
- if (false) {
+ if (Debug.SHOW_ENTITY_VIEW_AREA) {
g2d.setColor(Color.cyan);
g2d.drawRect(x, y, width, height);
}
Index: src/games/stendhal/common/Debug.java
===================================================================
RCS file: /cvsroot/arianne/stendhal/src/games/stendhal/common/Debug.java,v
retrieving revision 1.79
diff -u -r1.79 Debug.java
--- src/games/stendhal/common/Debug.java 12 Nov 2009 21:48:35 -0000 1.79
+++ src/games/stendhal/common/Debug.java 20 Nov 2009 23:50:47 -0000
@@ -39,5 +39,8 @@
*/
boolean SHOW_LIST_SIZES = false;
-
+ /**
+ * it shows entity's view area
+ */
+ boolean SHOW_ENTITY_VIEW_AREA = false;
}