| Version 20 (modified by , 14 years ago) ( diff ) |
|---|
Contributing documentation to QtWebKit
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. Contributions to the C++ API documentation should follow the standard contribution model and is not covered here.
QtWebKit currently comes with a lot of documentation for C++ developers, and we'd like to extend the documentation also for web developers.
The documentation sources are in qdoc format, stored together with the source code in the WebKit SVN. Documentation contributions are submitted to the project similarly as source code contributions -- for instance, documentation changes need to be reviewed before they are committed.
The qdoc3 tool
The qdoc3 markup is a simple wiki-like format. The qdoc3 tool is documented here: http://qt.gitorious.org/qt/pages/DocManual.
For 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.
On 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.
Getting access to the existing documentation source files
A 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/
It'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
Building the documentation articles
TBD: the qdoc command for building the articles.
Including an explicit license
For new document articles, you must include the following explicit license text at the bottom:
This document and any changes thereto are licensed under the Creative Commons Attribution-Share Alike 2.5 License Agreement.
The full license text is available here: http://creativecommons.org/licenses/by-sa/2.5/legalcode. To 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.
Submitting a documentation contribution
Documentation 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.
No matter the target of the change, it should be submited for review using bugzilla, as specified below:
- Make your changes. Typically, you would change existing qdoc files or create new qdoc files;
- Make sure it's correctly parsed by qdoc3, thus generating a valid result;
- Create a bug in the WebKit bugzilla. Use this template as the starting point: http://webkit.org/new-qtwebkit-bug.
- Component: "New bugs";
- Severity: usually "Enhancement", unless it's a more serious bug in existing documentation;
- Version: "528+ (Nightly build)";
- Assignee: "Ademar Reis";
- 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;
- Title: "[Qt] docs: ..." (replace ... with your own simple description of the change). Please don't forget the [Qt] prefix;
- Description: Describe the changes, which QtWebKit release it's targeted at and, if applicable, the motivation behind the changes;
- Attach all changed qdoc files, images and resources. Add a short description for each attachment but leave the other fields as they are.
- Wait for review comments and make a new version of the qdoc file as necessary;
- The bug will be closed once the change is included in the official repository(ies).
Having your documentation contribution cherry picked to a previous QtWebKit release
Ideally 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 email] or over IRC (ademar on freenode.net) to get your changes cherry-picked.
Communication
Feel free to use the QtWebKit webkit-qt Mailing List and the #qtwebkit IRC channel on freenode.net to discuss documentation, too.
Submitting patches directly
If 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.
Follow the intructions on the project wiki on how to contribute patches to QtWebKit (checkout source code, install dependencies, get used to the development tools, etc).
