HACKING

   1 Testing
   2 =======
   3
   4 jhbuild --no-interact build 2>&1 | tee build.log
   5 grep "gtkdoc-* line" build.log
   6
   7 jhbuild buildone --no-net glib
   8
   9 Since 1.23 we do have a snapshot feature to check the stability of the generated
  10 xml/html. Simply run "make snapshot" under tests. Then make changes and run
  11 "make check". The tests/sanity.sh will check for delta. If you want to inspect
  12 what delta a change created, you can git checkout a revision before the change,
  13 "make snapshot", go back to head and "make check", the sanity.sh test will now
  14 fail and show the delta.
  15
  16 Releasing
  17 =========
  18
  19 http://live.gnome.org/MaintainersCorner/Releasing
  20
  21 export OLD_VER=1.27
  22 export NEW_VER=1.28
  23 export OLD_VER_TAG=$(echo ${OLD_VER} | tr '.' '_')
  24 export NEW_VER_TAG=$(echo ${NEW_VER} | tr '.' '_')
  25
  26
  27 - bump release date in:
  28   help/manual/C/index.docbook
  29 - bump version in (x.y.1 -> x.y+1)
  30   configure.ac
  31
  32 - update NEWS
  33   ./bugzilla.py general ${NEW_VER} gtk-doc >RELNOTES.txt
  34   git log --summary --format=short GTK_DOC_${OLD_VER_TAG}.. >ChangeLog-${NEW_VER}
  35   grep "Author:" ChangeLog-${NEW_VER} | sed 's/Author:\(.*\)\ <.*>/\1/' | sort | uniq >>RELNOTES.txt
  36   and then copy to NEWS
  37
  38 - commit
  39   git add configure.ac NEWS help/manual/C/index.docbook
  40   git commit -m"release: update news and date in manual"
  41   git push
  42
  43 - dist
  44    TAR_OPTIONS="--owner=root --group=root" make distcheck
  45
  46 - tag
  47   git tag -a GTK_DOC_${NEW_VER_TAG} -m"release: ${NEW_VER}"
  48   git push origin GTK_DOC_${NEW_VER_TAG}
  49
  50 - release
  51   scp gtk-doc-${NEW_VER}.tar.xz <user>@master.gnome.org:
  52   scp NEWS <user>@master.gnome.org:gtk-doc-${NEW_VER}.news
  53   scp ChangeLog-${NEW_VER} <user>@master.gnome.org:gtk-doc-${NEW_VER}.changes
  54   ssh <user>@master.gnome.org
  55   ftpadmin install gtk-doc-1.12.tar.xz
  56   exit
  57
  58 - bump versions in:
  59   configure.ac
  60   help/manual/C/index.docbook
  61   NEWS
  62
  63 - commit
  64   git add configure.ac NEWS help/manual/C/index.docbook
  65   git commit -m"release: bump versions and back to development"
  66   git push
  67
  68 - update web-pages (gtk-web/gtk-doc)
  69   git add gtk-doc/news.php
  70   git commit -m"gtk-doc: new release (${NEW_VER})"
  71   git push
  72
  73 - if we want a icon on the newsfeed, we should copy a icon like on
  74   http://ftp.acc.umu.se/pub/GNOME/sources/rhythmbox/rhythmbox.png
  75   e.g. /usr/share/icons/hicolor/48x48/apps/devhelp.png
  76
  77 Optimizing & Meassuring
  78 =======================
  79
  80 cd tests/gobject/docs/html
  81 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "tester" --stringparam gtkdoc.version "1.12" ../../../../gtk-doc.xsl ../tester-docs.xml
  82 ~ 1.1 sec.
  83 time saxon ../tester-docs.xml ../../../../gtk-doc.xsl gtkdoc.bookname="tester" gtkdoc.version="1.12"
  84 ~ 53 sec.
  85 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "tester" --stringparam gtkdoc.version "1.12" /usr/share/yelp-xsl/xslt/docbook/html/db2html.xsl ../tester-docs.xml
  86 ~ 0.7 sec
  87
  88 cd /your/project/docs/html
  89 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "foo" --stringparam gtkdoc.version "1.12" /usr/share/gtk-doc/data/gtk-doc.xsl ../buzztrax-core-docs.xml
  90 real  0m6.633s  user    0m6.464s  sys   0m0.128s
  91 real    0m6.459s  user  0m6.384s  sys   0m0.068s
  92
  93 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "buzztrax-core" --stringparam gtkdoc.version "1.12"  /usr/share/yelp-xsl/xslt/docbook/html/db2html.xsl ../buzztrax-core-docs.xml
  94 real    0m3.312s  user  0m3.224s  sys   0m0.076s
  95 real    0m3.549s  user  0m3.464s  sys   0m0.076s
  96
  97
  98 xsltproc --profile data.xsl data.xml 2>report.txt
  99 cat report.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o report.png
 100
 101 one can now use "GTKDOC_PROFILE=1 make" to run this during gtkdoc-mkhtml. It
 102 still needs a change in gprof2dot.py
 103 https://bugzilla.gnome.org/show_bug.cgi?id=612186#c3
 104
 105 Performance tips:
 106 * uses keys when we have slow xpath selects
 107   http://www.xml.com/pub/a/2002/02/06/key-lookups.html
 108
 109 Troubles with parsing regexps
 110 =============================
 111 Test regexps online:
 112 http://www.solmetra.com/scripts/regex/index.php
 113