Tags:
dev_essential1Add my vote for this tag process1Add my vote for this tag create new tag
, view all tags

Patch Guidelines

The TWiki developers produce patches every so often to correct problems in TWiki. but that's not the only use of patching; you can use patches to contribute back to TWiki as well.

Why patches?

So... You've implemented a nice feature (or bug fix) in your local TWiki, and would like to see it get into the core code, but you don't have checkin access. The first thing to consider is if this feature can be implemented as a Plugin . If not, then the best way to offer a change to the core code is to produce a 'patch' - a set of context diffs produced by the diff tool (preferably GNU diff). This is much better than providing the modified files, because:

  • Patches are easier to review than complete files, since they include only your changes and are plain text
  • Patches are easy to apply to the sources in the Subversion repository
  • Patches are small

Here's how to produce a patch:

  1. Just do diff -c from the old file to the new file, and repeat for each file changed (unified diffs are fine as well, just use diff -u). Use a well-defined version, such as a TWiki production release withut local changes.
  2. diff -N will put into a diff any files that are deemed to be missing.
  3. Once you have a set of patch files, concatenate them all into a single file and test your patch against the original set of files, using patch -i with suitable options.
  4. If you are proposing an enhancement, then attach your patch to a suitable page in Codev, as a .patch or .diff file. Very small patches can be included inline in the page, but please include the full contents of the patch file to simplify applying it, and don't do this if there are any TAB characters used in indentation as this may not work well.
  5. Make sure you say exactly what version of TWiki you patched.
    • if you made any other local changes to the TWiki source, please be careful to exclude them from your patch.
  6. If you are fixing a bug, please attach the patch file to the bug report in Bugs web.

Patch tools for your platform

  • On Linux, good versions of diff and patch are included.
  • On Unix, you can get hold of GNU diff and patch quite easily, try TWikiOnUnix for useful sites for your Unix variant, or just Google:diffutils and GNU Patch.
  • On Windows, just download CygWin and install the diffutils and patch packages using the setup tool.

Coding standards

Please read and apply all the advice on coding standards linked from the Codev.ReadmeFirst guidelines. Keeping to these, even on simple things such as indentation and variable naming, makes it much easier to incorporate your patch and ensures that TWiki code is reasonably consistent overall, improving readability.

Testing

Make sure write the code so that is usable in the TWiki core - i.e. it doesn't depend on your particular site's setup, and runs on (at least) Unix/Linux, and preferably Windows as well. If you have a subversion checkout area, run the unit tests and exercise the manual tests on your patched code.

How to apply a patch

See HowToApplyPatch

-- Contributors: RichardDonkin, PeterThoeny, CrawfordCurrie

Comments?

The details of producing patches could be improved, but context diff patches would be a great improvement so this is a reasonable first step. -- RD

Suggestion: start and close your changes with your initials and perhaps a reference to a twiki discussion topic. This way it will be easier to track down potential problems when multiple "after-market" patches have been applied. For example:

+    #mhw  TWiki:Support/LoginNameAndNtlm
+    # In Windows environment ntlm/sspi REMOTE_USER looks like "DOMAIN\jsmith"
+    # discard domain name and keep login name
+    if( $ENV{'AUTH_TYPE'} eq 'NTLM' ) {
+        my( @domainuser ) = split(/\\/, $remoteUser);
+        $remoteUser = $domainuser[1];
+        }
+    #/mhw

-- MattWilkie - 28 Jul 2003

  1. We could provide tools to help people produce patches
  2. Is there a way of bundling a patch with a test package that ensures that the person's patch does what they think it does?

-- MartinCleaver - 28 Oct 2003

I'll bundle these up as an command set for Rafael's TWikiShellContrib, but the following is a useful way to produce a diff on a local installation that you've changed.

The following will pick up CairoRelease (1742), and then copy your files over it. After that we use "svn diff" to find out what has changed, and "svn status" to pick up new files.

Assumes you start with a subdir called twiki. Make your own backup

$ tar cvzf twiki-dev.tgz twiki
$ mv twiki twiki-dev
$ mkdir twiki
$ cd twiki
$ svn co -r1742 http://svn.twiki.org/svn/twiki/trunk/ .
$ cd ..
$ tar xzvf twiki-dev.tgz 
$ cd twiki
$ svn status | grep '?' | cut -d' ' -f7 | xargs echo > new.files
$ zip -D -r new.files.zip `cat new.files`
$ svn diff > diffed.files

An alternative is to use the TWikiReleaseTrackerPlugin

None of this will be necessary once we implement the PostCairoDevelopmentModel and it doesn't work for data or pub because they are damn well not in the repository.

-- MartinCleaver - 22 Oct 2004

NB. diff -N will put into a diff any files that are deemed to be missing.

-- MartinCleaver - 22 Oct 2004

1/2008 one cannot register to report bugs.... Sooo how do I make a report???

-- AsphaltJesus - 16 Jan 2008

You register on twiki.org and after a while you can report bugs. It takes some time before the user account is sync'ed over to the Bugs web which is on another server setup.

-- LarsEik - 17 Jan 2008

where 'after some time' is documented in the orange header on every topic in the Bugs web as "NOTE: Do not register here at develop.twiki.org, please use your twiki.org account to login (login works here after one hour of registration on twiki.org)."

-- SvenDowideit - 17 Jan 2008

Edit | Attach | Watch | Print version | History: r24 < r23 < r22 < r21 < r20 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r24 - 2008-01-17 - SvenDowideit
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.