| 22 | | 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 |
| | 22 | == Building the documentation articles == |
| | 23 | |
| | 24 | TBD: this will require some additional tools: To build the complete the QtWebKit documentation simply run {{{make docs}}} in your build directory, i.e. {{{WebKitBuild/Release}}}. The output will be generated in HTML in the {{{doc/html}}} subdirectory. |
| | 25 | |
| | 26 | TBD: should writers just use qdoc directly to build the articles? |
| | 27 | |
| | 28 | == Submitting a documentation contribution == |
| | 29 | |
| | 30 | 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). |
| | 31 | |
| | 32 | * Make your changes. Typically, you would change existing qdoc files or create new qdoc files. |
| | 33 | * Create a bug in the WebKit bugzilla. Use this template as the starting point: http://webkit.org/new-qtwebkit-bug. |
| | 34 | * Leave the component as "New bugs". |
| | 35 | * Use the severity "Enhancement" if your patch is an improvement and not related to a bug in documentation. |
| | 36 | * Select 528+ (Nightly build) as the version |
| | 37 | * Enter "ademar.reis@openbossa.org" as the assignee |
| | 38 | * enter a short title to the change in the summary field. Don't omit the [Qt] in the beginning |
| | 39 | * enter a description of the change in the description field |
| | 40 | * Attach the changed qdoc file or the new qdoc file n the bug report |
| | 41 | * Wait for Ademar to prepare a change log and a patch |
| | 42 | * Wait for review comments and make a new version of the qdoc file as necessary |
| | 43 | |
| | 44 | == Having your documentation contribution cherry picked to a previous QtWebKit release == |
| | 45 | |
| | 46 | You can work with QtWebKit release manager Ademar Reis to get your changes cherry picked to a QtWebKit release. |
| | 47 | |
| | 48 | == Communication == |
| | 49 | |
| | 50 | 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. |
| | 51 | |
| | 52 | |
| | 53 | == Appendix: Installing git and checking out the documentation sources using git == |
| | 54 | |
| | 55 | 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. |
| | 56 | |
| | 57 | 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 |
| 49 | | The C++ API documentation is included in line in the C++ source files. Standalone documentation articles are in the WebKit/qt/docs directory. |
| 50 | | |
| 51 | | == TODO: installing other tools == |
| 52 | | |
| 53 | | TODO: what other tools are needed to build the documentation? |
| 54 | | |
| 55 | | == Building the documentation articles == |
| 56 | | |
| 57 | | To build the QtWebKit documentation simply run {{{make docs}}} in your build directory, i.e. {{{WebKitBuild/Release}}}. The output will be generated in HTML in the {{{doc/html}}} subdirectory. |
| 58 | | |
| 59 | | If you also need to work on the C++ API documentation that refers to the Qt API documentation, then you need to build Qt from sources. See http://trac.webkit.org/wiki/QtWebKitContrib for more information. |
| 60 | | |
| 61 | | == Submitting a documentation contribution == |
| 62 | | |
| 63 | | 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). |
| 64 | | |
| 65 | | When using the git repository to access the sources, the steps to submit a patch are roughly as follows. Please see the WebKit project's page about [http://webkit.org/coding/contributing.html contributing] for more information. |
| 66 | | |
| 67 | | * Make your changes in the webkit source code directory. Typically, you would change existing qdoc files or create new qdoc files. |
| 68 | | * Run the {{{WebKitTools/Scripts/prepare-ChangeLog}}} script to create an entry for your changes in each relevant ChangeLog file. |
| 69 | | * Edit the ChangeLog files reported by the prepare-ChangeLog script: |
| 70 | | * If you work on a task without bug report on bugs.webkit.org yet, create a bug report. Use the severity "Enhancement" if your patch is an improvement and not related to a bug. |
| 71 | | * Add a short description and paste the bug URL below it. Add an extra line and a detailed description if necessary. |
| 72 | | * Precede the short description with "[Qt]" since your documentation patch is specific to the Qt port of WebKit. |
| 73 | | * The description text should be the same in all ChangeLog files. |
| 74 | | * Keep the "Reviewed by NOBODY (OOPS!)." line in the ChangeLog files, it will be edited by the bot or person that will commit your fix. |
| 75 | | * Do a {{{git diff > patchname.patch}}} to create your patch (use {{{--cached}}} if you first did a {{{git add}}} to put your changes in the git index) |
| 76 | | * Attach the patch to the bug report, set the {{{review}}} flag to '?' and the {{{commit-queue}}} flag to '?' |
| 77 | | * Wait :) |
| 78 | | |
| 79 | | == Having your documentation contribution cherry picked to a previous QtWebKit release == |
| 80 | | |
| 81 | | TBD |
| 82 | | |
| 83 | | == Communication == |
| 84 | | |
| 85 | | 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. |
