From kde-commits Fri Oct 26 22:31:42 2007 From: Clarence Dang Date: Fri, 26 Oct 2007 22:31:42 +0000 To: kde-commits Subject: branches/kolourpaint/control/devel-doc Message-Id: <1193437902.427151.5921.nullmailer () svn ! kde ! org> X-MARC-Message: https://marc.info/?l=kde-commits&m=119343791307780 SVN commit 729776 by dang: Polish M +4 -8 README.txt A releasing/backport-releases/README.txt M +1 -2 releasing/backport-releases/announce places.txt M +11 -51 releasing/maintaining.txt M +3 -3 testing/code-reliability.txt M +62 -93 testing/testing.txt --- branches/kolourpaint/control/devel-doc/README.txt #729775:729776 @@ -1,9 +1,9 @@ KolourPaint -This is a concise guide for maintaining and modifying KolourPaint. Highly -dynamic, implementation details, and hacks not really worth mentioning, are -described in source code comments. +This is a concise set of docs for maintaining and modifying KolourPaint. +Highly dynamic, implementation details, and hacks not really worth mentioning, +are described in source code comments. Future Directions @@ -19,11 +19,11 @@ * Steal ideas from other editors - People ~~~~~~ Clarence Dang is the founder and was the main developer. + Thurston Dang provides advice on user interfaces changes and wrote the DocBook documentation (kdegraphics/doc/kolourpaint). @@ -31,7 +31,3 @@ hopeless ones. Nuno Pinheiro and Danny Allen replaced most of the icons with newer ones. - - - - --- branches/kolourpaint/control/devel-doc/releasing/backport-releases/announce places.txt #729775:729776 @@ -6,5 +6,4 @@ kde-dot [1.0] [1.0.1 private email] [N/A] [1.0.2] [N/A] PCLinuxOnline [1.0.2] [pending] NewsForge -Slashdot -OSNews +OSNews --- branches/kolourpaint/control/devel-doc/releasing/maintaining.txt #729775:729776 @@ -1,39 +1,15 @@ Welcome Maintainer (or Forker and it also depends how you pronounce it :P)! -This is probably the first file you should read. You must read this before -every release. +You must read this before every release. The idea as maintainer is that you have a _complete_ idea of the state of KolourPaint every so often (mandatory before a release) in every active -branch: +branch -- see code-walk-thru/resources.txt for descriptions of each branch. -trunk/KDE/kdegraphics/{doc/,}kolourpaint -* In an unknown state ATM - -branches/KDE/3.5/kdegraphics/{doc/,}kolourpaint -* Releaseable except for version number change, used for any future KDE 3.5 - releases - -branches/KDE/3.4/kdegraphics/{doc/,}kolourpaint -* Releaseable except for version number change, used for any future KDE 3.4 - releases - -branches/KDE/3.3/kdegraphics/{doc/,}kolourpaint -* Releaseable, used for any future KDE 3.3 (unlikely) - -branches/kolourpaint/1.2_kde3/ -* Releaseable - To reduce your workload, stop supporting a branch. Add a file -"BRANCH_STATUS" to the dead branch explaining the situation. Dead -branches: +"BRANCH_STATUS" to the dead branch explaining the situation. -branches/kolourpaint/1.0/ -Note: Debian currently uses the 3.3 branch so you had better support it -until the next release! - - For each release (whether tagged by KDE or as a standalone release), for each active branch (even if the branch is not going to be released soon): @@ -42,36 +18,20 @@ state of the branch (branches/kolourpaint/control/stamp helps here). Review every commit after the last known good state. Reject, change - and/or port the change to other relevant branches. You must be - paranoid else an unwanted change will slip through or a wanted change - will not be backported. + and/or port the changes to other relevant branches. Act on TODO. - To help keep track of this, use the KDE Commit Filter (google it) and - watch all active branches. + To help keep track of this, use the KDE Commit Filter and watch all + active branches. -2. Grep sources for "SYNC" (assumptions on compilation and run environment) - & "sync:" (assumptions between >= 2 bits of code) and check that those - assumptions still hold. +2. Run scripts/find_issues_before_release.sh and check that those assumptions + still hold. 3. Go through your inbox, kde-apps.org, sf.net/projects/kolourpaint and the - KDE buglist collecting feedback into TODO and credits into AUTHORS. + KDE buglist, fixing what is necessary and collecting feedback into TODO & + credits into AUTHORS. - The KolourPaint policy is: anyone who contributes an idea or reports a - bug deserves a mention in the credits even if the idea/bug has been - suggested by someone before and/or even if the idea appears ridiculous. - - You will not believe the lengths some people go to, to get into the - credits. KolourPaint will make it easy for those people, encourage - feedback and keep everyone happy :) - - Update AUTHORS if this is trunk/KDE/ (not in branches as it would be - too painful and might encounter message freeze issues). - 4. Update all docs (README, NEWS, BUGS etc.). Increment version number unless there are _absolutely_ no changes - (including text files, docs etc.). - -Loop until this reaches a stable state. - + (including text files, docs, kolourpaint.desktop etc.). --- branches/kolourpaint/control/devel-doc/testing/code-reliability.txt #729775:729776 @@ -7,9 +7,9 @@ This is why the Coverity static code analyser failed to find a single non-false-positive out of more than 50 thousand lines of code. -You will not get memory errors in KolourPaint code, except some memory -leaks on application termination due to some missing destruction (but this -is cleaned up by the OS anyway). However: +You will probably not get memory errors in KolourPaint code, except some +memory leaks on application termination due to some missing destruction (but +this is cleaned up by the OS anyway). However: 1. The selection code, combined with undo/redo, is very complicated. It would not be surprising if there was a path that causes a crash --- branches/kolourpaint/control/devel-doc/testing/testing.txt #729775:729776 @@ -1,128 +1,97 @@ -blackbox test all capabilities (remember mask & no mask document cases) -with and without valgrind; doc all tests -test SYNC - - - Testing -There are 2 kinds of documents: -RGB - the kind of document you get when you start KolourPaint or click "File / -New". +1. Reference Implementation +2. Clean Install +3. Test Scenarios +4. Test Cases -RGBM - RGB with a 0/1 transparency mask. To get this, either open such a file - or draw on an RGB document using a transparent color. There are - also some (careless) code paths in KolourPaint that convert from RGB to RGBM - even when no transparency in introduced. -There are separate code paths (with large areas of commonality) for both -so when you change something in KolourPaint, you must test both. +1. Reference Implementation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -KolourPaint code does not support QPixmap's with alpha channels -(see the explanation at TODO). The -following are common examples of incorrect code: +If the behavior of any operation is in doubt, KolourPaint from KDE 3.4.0 +and running under KDE 3.4.0 (e.g. KDE 3.5 introduced a Recent Files bug), +as shipped by Fedora Core 4, on a 24-bit screen, is the most tested +configuration of KolourPaint and should be considered the reference +implementation, except for bugs that were fixed in later versions. Later +versions in the KDE 3.4.x and KDE 3.5.x series (even with those bugs fixed) +are not reference implementations because they were not as well tested. -A. kpImage image; - QPainter p (&image); +2. Clean Install +~~~~~~~~~~~~~~~~ - // This is likely to introduce an alpha channel. - p.anyMethod (); +Remove any installed KolourPaint files in $KDEDIR and $KDEHOME +("find $KDHEOME $KDEDIR -iname '*kolourpaint*'"). - Change to: +This includes: + $KDEHOME/share/config/kolourpaintrc + $KDEHOME/share/apps/kolourpaint/ [kolourpaintui.rc in here specifies + toolbar config] + TODO: who specifies shortcuts? - kpImage image; - // This calls QPainter but in tricky ways to avoid introducing an alpha - // channel. - kpPainter::anyMethod (&image); +3. Test Scenarios +~~~~~~~~~~~~~~~~~ -B. QPixmap pixmap; +1. Try different screen modes (15/16-bit and 24-bit). + See pixmapfx/ documentation. - QPainter p (&pixmap); +2. Try with XRENDER on and off. + See pixmapfx/ documentation. - // This is likely to introduce an alpha channel. - p.anyMethod (); +3. Test all operations on images that don't have masks and images + with masks. - Change to: + There are 2 kinds of documents: - QPixmap pixmap; + RGB - the kind of document you get when you start KolourPaint or click + "File / New". - // This calls QPainter but in tricky ways to avoid introducing an alpha - // channel. - kpPixmapFX::anyMethod (&pixmap); + RGBM - RGB with a 0/1 transparency mask. To get this, either open such a + file or draw on an RGB document using a transparent color. There + are also some (careless) code paths in KolourPaint that convert from + RGB to RGBM even when no transparency needs to be introduced. -C. QPixmap pixmap (width, height); + There are separate code paths (with large areas of commonality) for both + so when you change something in KolourPaint, you should test both. + See pixmapfx/ documentation. - // is uninitialized and may have an alpha channel. - // If it does, calling kpPixmapFX::anyMethod() will trip an assert. - kpPixmapFX::anyMethod (&pixmap); +4. Trying running under valgrind - Change to: - // While this does not initialize the image data of , - // it establishes the no-alpha-channel invariant ... - QPixmap pixmap = kpPixmapFX::newPixmap (width, height); +4. Test Cases +~~~~~~~~~~~~~ - // ... so this is safe to call. - kpPixmapFX::anyMethod (&pixmap); +Exhaustively test all functionality ostensibly accessible in the GUI. +NEWS and the user handbook should describe additional functionality. - - -Testing: - -Uninstall and install (needs find $KDEDIR -iname '*kolourpaint*') -rm $KDEHOME/share/config/kolourpaintrc -rm -rf $KDEHOME/share/apps/kolourpaint/ [kolourpaintui.rc here specifies -toolbar config] -TODO: who specifies shortcuts? - -Exhaustive test kolourpaint (open and save and a bit of doodling, -Transparency -) and help - - - - -Reference Implementation - -If the behavior of any operation is in doubt, KolourPaint from KDE 3.4.0 -and running under KDE 3.4.0 (e.g. KDE 3.5 introduced a Recent Files bug), -as shipped by Fedora Core 4, on a 32-bit screen, is the most tested configuration of KolourPaint and should be -considered the reference implementation, except for bugs that were fixed -in later versions. Later versions in the KDE 3.4.x and KDE 3.5.x series -(even with those bugs fixed) are not reference implementations because -they were not as well tested. - - - -Test cases -~~~~~~~~~~ - TODO: List all functionality in every widget as test cases. +Test 1 +------ +Steps: +1. "kolourpaint doesnotexist.png" +2. [optional modification of image] +3. CTRL+S forces a dialog open because it does not know what format it should + be saved in. -kolourpaint doesnotexist.png -[optional modification of image] -CTRL+S forces a dialog open because it does not know what format it should -be saved in. +Test 2 +------ +Steps: +1. Open a JPEG. +2. CTRL+S should bring up file dialog since JPEG quality is unknown. -Also for JPEGs since don't know qualtiy. +Test 3 +------ - - - - -KolourPaint saving also handles KImageIO writer not existing for format. - - - - - +Steps: +1. Open a file whose format is supported for reading but not writing. +2. CTRL+S should bring up a file dialog.