Changes between Version 19 and Version 20 of QtWebKitDocContrib


Ignore:
Timestamp:
Oct 7, 2010, 5:30:45 AM (15 years ago)
Author:
Ademar Reis
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • QtWebKitDocContrib

    v19 v20  
    1 
    21= Contributing documentation to QtWebKit =
    32
    4 UNDER CONSTRUCTION! This wiki page contains the information that is relevant for technical writers contributing documentation to QtWebKit.This page covers how to contribute standalone articles and changes to the existing articles. Contributing C++ API documentation is not covered here.
     3UNDER CONSTRUCTION! This wiki page contains the information that is relevant for technical writers contributing documentation to QtWebKit. This page covers how to contribute standalone articles and changes to the existing articles. Contributions to the C++ API documentation should follow the standard contribution model and is not covered here.
    54
    65QtWebKit currently comes with a lot of documentation for C++ developers, and we'd like to extend the documentation also for web developers.
    … …  
    1413For Windows users, the easiest way to get the qdoc3 command line tool is to install the Qt SDK for Windows and add Qt's bin directory to the system's PATH environment variable in the Windows Control Panel. For instance, if you install Qt SDK version 2010.3 to the default location, the qdoc3.exe tool will be in C:\Qt\2010.03\qt\bin.
    1514
    16 On Mac OS X, the qdoc3 binary has not been previously included in the Qt SDK, but as of Qt 4.7.0, the qdoc3 binary is included in the Qt SDK. After installation, qdoc3 should already be in the PATH.
     15On Mac OS X, the qdoc3 binary is included only in newer versions, starting with Qt 4.7.0. After installation, qdoc3 should already be in the PATH.
    1716
    1817== Getting access to the existing documentation source files ==
    1918
    20 The simplest way to get the existing documentation files is to use the web interface of http://svn.webkit.org/repository/webkit/trunk/WebKit/qt/docs/. That URL points to the WebKit/qt/docs directory where all the Qt specific documentation articles are stored.
     19A convenient way to get the whole documentation directory tree is to use SVN and check out the docs directory: http://svn.webkit.org/repository/webkit/trunk/WebKit/qt/docs/
    2120
    22 A convenient way to get the whole documentation directory tree is to use SVN and check out the docs directory.
     21It's also possible to browse the source-code and get individual files if one prefers to: http://trac.webkit.org/browser/trunk/WebKit/qt/docs
    2322
    2423== Building the documentation articles  ==
    25 
     24{{{
    2625TBD: the qdoc command for building the articles.
     26}}}
    2727
    2828== Including an explicit license ==
    2929
    30 For new document articles, you must  include the following explicit license text at the bottom of the article:
     30For new document articles, you must  include the following explicit license text at the bottom:
    3131
    3232This document and any changes thereto are licensed under the Creative Commons Attribution-Share Alike 2.5 License Agreement.
    3333
    34 The full license text is available here:  http://creativecommons.org/licenses/by-sa/2.5/legalcode.
    35 To the extent any examples and code snippets are referenced in this document, such examples and code snippets are licensed under the BSD license:  www.opensource.org/licenses/bsd-license.php.
     34The full license text is available here: http://creativecommons.org/licenses/by-sa/2.5/legalcode.
     35To the extent any examples and code snippets are referenced in this document, such examples and code snippets are licensed under the BSD license: http://www.opensource.org/licenses/bsd-license.php.
    3636
    3737== Submitting a documentation contribution ==
    3838
    39 Documentation is contributed to the WebKit SVN (the trunk of the project). By default, the documentation change will then be included in the next QtWebKit release that is branched off from the trunk. It is also possible to "cherry-pick" documentation changes to previous versions of QtWebKit (see below). In some cases, documentation changes are needed in a certain release branch only.
     39Documentation is contributed to the WebKit SVN (the trunk of the project) by default, meaning it will be part of the next QtWebKit release that is branched off from the trunk. If the change applies to an already branched release (new branches are created some time before an official release), it can be "cherry-picked" (see below). There are also cases where documentation changes apply only to a certain release branch.
    4040
    41  * Make your changes. Typically, you would change existing qdoc files or create new qdoc files.
     41No matter the target of the change, it should be submited for review using bugzilla, as specified below:
     42
     43 * Make your changes. Typically, you would change existing qdoc files or create new qdoc files;
     44 * Make sure it's correctly parsed by qdoc3, thus generating a valid result;
    4245 * Create a bug in the WebKit bugzilla. Use this template as the starting point: http://webkit.org/new-qtwebkit-bug.
    43    * Leave the component as "New bugs".
    44    * Use the severity "Enhancement" if your patch is an improvement and not related to a bug in documentation.
    45    * Select 528+ (Nightly build) as the version
    46    * Enter "ademar.reis@openbossa.org" as the assignee
    47    * As the reporter of the bug, you will automatically receive email updates when the bug changes, for example when there are comments from reviewers. If you'd like a colleague or a mailing list to receive email notifications, you can add the email addresses in the CC field.
    48    * enter a short title to the change in the summary field. Don't omit the [Qt] prefix in the beginning
    49    * enter a description of the change in the description field and which QtWebKit releases are applicable.
    50  * Attach the changed qdoc file or the new qdoc file n the bug report. If your document embeds images, attach them to the bug report as well. When attaching documents, just add a short description and leave the other fields as they are.
    51  * Wait for review comments and make a new version of the qdoc file as necessary
     46   * Component: "New bugs";
     47   * Severity: usually "Enhancement", unless it's a more serious bug in existing documentation;
     48   * Version: "528+ (Nightly build)";
     49   * Assignee: "ademar.reis@openbossa.org";
     50   * CC: As the reporter, you'll automatically receive e-mails whenever the bug changes (reviews, comments, etc). If you'd like someone else to receive these updates, add their e-mails here;
     51   * Title: "[Qt] docs: ..." (replace ... with your own simple description of the change). Please '''don't''' forget the [Qt] prefix;
     52   * Description: Describe the changes, which QtWebKit release it's targeted at and, if applicable, the motivation behind the changes;
     53   * Attach all changed qdoc files, images and resources. Add a short description for each attachment but leave the other fields as they are.
     54 * Wait for review comments and make a new version of the qdoc file as necessary;
     55 * The bug will be closed once the change is included in the official repository(ies).
    5256
    5357== Having your documentation contribution cherry picked to a previous QtWebKit release ==
    5458
    55 You can work with QtWebKit release manager Ademar Reis by email or over IRC to get your changes cherry picked to a QtWebKit release.
     59Ideally changes should go to {{{trunk}}} before being cherry-picked into a stable release. If the change doesn't apply to trunk, just get in touch with Ademar by [ademar.reis@openbossa.org email] or over IRC ({{{ademar}}} on freenode.net) to get your changes cherry-picked.
    5660
    5761== Communication ==
    5862
    59 We can use the QtWebKit [http://lists.webkit.org/mailman/listinfo.cgi/webkit-qt webkit-qt Mailing List] and the #qtwebkit IRC channel on freenode.net to discuss documentation, too.
     63Feel free to use the QtWebKit [http://lists.webkit.org/mailman/listinfo.cgi/webkit-qt webkit-qt Mailing List] and the #qtwebkit IRC channel on freenode.net to discuss documentation, too.
    6064
    61 == Appendix: Installing git and checking out the documentation sources using git ==
     65== Submitting patches directly ==
    6266
    63 Git is a revision control system that many QtWebKit developers use to work with the WebKit SVN repository. It is not mandatory to use git or any other SVN client to contribute documentation. If you want to use git to be able to pull a local copy of the WebKit sources and documentation, here's how you can get started.
     67If you feel confortable with tools like {{{git}}}, {{{patch}}} and {{{diff}}}, you can submit patches instead of documentation files, thus facilitating the work of reviewers and integrators.
    6468
    65 WebKit SVN repository is mirrored at [http://gitorious.org/webkit Gitorious.org]. Before you can use Gitorious.org, you need to install git on your computer. Here are some instructions for git installation on different platforms: http://git-scm.com/download
     69Follow the intructions on the [https://trac.webkit.org/wiki/QtWebKit project wiki] on how to contribute patches to QtWebKit (checkout source code, install dependencies, get used to the development tools, etc).
    6670
    67  * On Windows, you can get git by installing Cygwin (from the link above). Cygwin is a distribution for several different tools, so during the installation, Cygwin will ask you to select the packages you want to install. Make sure you install at least the git package, and possibly also git-gui, a graphical user interface for git. The git package may not be installed by default. After installing Cygwin,  add the bin directory of the Cygwin installation to your system's PATH environment variable. The default location is C:\cygwin\bin.
     71== Useful links ==
    6872
    69 After installing git, you can verify your installation by typing {{{git}}} on the command line. If git has been installed and included in your PATH, you will see  a list of most commonly used git commands.
    70 
    71 Alternatively, you can Since the documentation is stored together with the source code, technical writes can also  check out the sources and documentation. Open a command prompt, go to your working directory for QtWebKit documentation, and type the following command:
    72 
    73 {{{
    74 git clone git://gitorious.org/webkit/webkit.git
    75 }}}
    76 
    77 Cloning the repository can take some time, so please be patient.
    78 
    79 Git repositories can have several branches. However, by default you should have the master branch of this repository checked out, which works fine for contributing documentation to QtWebKit.
    80 
    81 If you want to make sure you're using the master branch, you can see the remote branches you just fetched with this command:
    82 {{{
    83 git branch -r
    84 }}}
    85 
    86 And to switch to a branch simply use {{{git checkout branchname}}}
    87 
    88 
     73 * [https://trac.webkit.org/wiki/QtWebKit QtWebKit wiki main page]
     74 * [http://lists.webkit.org/mailman/listinfo.cgi/webkit-qt QtWebKit devel Mailing List]
     75 * [https://bugs.webkit.org/ WebKit bugzilla]
     76 * [http://svn.webkit.org/repository/webkit/trunk/ Source code browser]
     77 * [http://trac.webkit.org/browser/trunk/WebKit/qt/docs SVN documentation repository]