How to Contribute a Patch via Bugzilla

+Font size: + + + +

How to Contribute a Patch via Bugzilla

+Bugzilla is the Internet-based mechanism to facilitate contributions to any +Apache project. This includes changes to code and documents +(Patches), and also reports of flaws in the system (Bugs), and suggestions +for enhancement. +In this How-to we will concentrate on the Patch tracking capabilities of +Bugzilla. We will explain how to create your Bugzilla account, +how to enter a patch description, and finally how to attach the actual patch +file. +

+ This is documentation for past version v0.6 + (More)

+Intended Audience +
+Prerequisites +
+Steps +
- +1. Create your Bugzilla Account +
- +2. Enter a new bug report +
  - +Specify Version +
  - +Specify Component +
  - +Specify Platform +
  - +Specify Operating System (OS) +
  - +Specify Severity +
  - +Specify Initial State +
  - +Specify Assigned To +
  - +Specify URL +
  - +Carefully choose the Summary +
  - +Description +
  +
- +3. Send the patch report +
- +4. Create an attachment of the actual patch +
  - +Specify the file to be uploaded +
  - +Describe the attachment +
  - +Specify the contentType of the attachment +
  +
- +5. Submit the attachment +
- +6. Be patient +
- +7. Add more description or attachments if necessary +
- +8. Adding subsequent patches to the same document or program +
+
+Real World Extension +
+Tips +
- +Setting user preferences +
- +Review the bugzilla documentation +
- +Search Bugzilla +
+
+References +

+ +

Intended Audience

+This document is meant for first-time users of Bugzilla. +The web interface can be daunting, so this concise explanation will help +you to start. After your first patch submission, you can proceed to make more +substantial contributions. +

+As our example we use the contribution of a simple documentation patch for +the Apache Cocoon project. The principles apply to any project. +

+ +

Prerequisites

+Bugzilla contributors should: +

Understand what a Patch is and how to make one. +Note that a new complete document is still just a "patch", +though it does need separate treatment to a normal "diff". +
Understand that Bugzilla is the Apache Bug Database. Bugzilla does not +distinguish between a Bug report, a Patch submission, and an Enhancement suggestion. They are all "Bugs" as far as Bugzilla is concerned. +

+ +

Steps

+Here is how to proceed. Go to +Bugzilla +in another browser window. +

+ +

1. Create your Bugzilla Account

+Follow the link the home page to "Open a new Bugzilla account". +Do not worry, you will not be sent spam email nor bombarded with advertisements +by setting up this account. It is purely a workgroup tool. +

+Note that you can conduct queries in Bugzilla and review submissions without +having an account. However, to make a contribution you must have an account. +This ensures legitimacy. It also enables the system to send you +email automatically when your patch is applied by a Cocoon committer. +

+ +

2. Enter a new bug report

+Follow the "Enter a new bug report" link from the Bugzilla home page. First, +you will be asked to select the relevant project ... choose Cocoon 2 of course. +Next, you will be asked to provide your account details. Following that, you +will be presented an input form for the various details ... +

+ Bugzilla Screen

+ +

Specify Version

+This is the version of Cocoon that you prepared your patch against. Choose +Current CVS if you have an up-to-date local working copy +of HEAD branch or a very recent nightly build. Otherwise choose the relevant +release version. This is a very important step, as you will confuse the +committer if your changes do not match the repository. If you are unsure, then +please say so in the description at step 12. +

+ +

Specify Component

+Follow the "Component" link for description of the available +components. If you do not know which component is relevant, then just use +core. +

+ +

Specify Platform

+This is really meant for bug reporting. Perhaps it could be relevant for a +patch. You would usually specify the All option. +

+ +

Specify Operating System (OS)

+Really meant for bug reporting. Perhaps it could be relevant for a patch. +You would usually specify the All option. +

+ +

Specify Severity

+The impact that would arise if your patch is not applied. For a documentation +patch, the severity would usually be the default Normal. +However, if it addressed some serious lack or fixed a misguided configuration +statement, then the impact could be major. +

+ + +(The enhancement option would not be used for a patch, as it is +intended for suggesting something that should be done. Use this option wisely. +It would be better to discuss it on the mailing list first.) +

+ +

Specify Initial State

+Use the New option. +

+ +

Specify Assigned To

+Leave it blank. Your patch will be automatically assigned to the +cocoon-dev mailing list. When a committer takes on your patch, +that committer will assign the bug to their own email address. This pevents +duplication of effort by other committers. +

+The Cc field can be used if you need the bug reports, and any follow-up, to be +copied to some other person. Remember that your report will be sent +automatically to the cocoon-dev mailing list, so you do not need +to Cc anyone there. +

+ +

Specify URL

+If the patch refers to a particular document, then provide the website URL. +If it refers to an issue with one of the local Cocoon Samples, then provide +the localhost URL. +

+ +

Carefully choose the Summary

+The summary will become the all-important title of the bug. Use it wisely. You want +to draw attention to your patch. Just as with posting email to the listervers, +choosing a poor title may cause your posting to be easily overlooked. +Use up all the characters available ... about 60 maximum. +

+Start the Summary with the [PATCH] tag. This will ensure that it +is included in the Cocoon automated patch queue summary posted to the mailing +lists. The patch queue summary reminds people what patches are pending. If you +omit this tag, then your patch may easily be overlooked. +

+ +

Description

+Provide a brief explanation of what your patch does. Supply any instructions +to help the committer apply your patch efficiently. Note any issues that may +remain. It may help to list each file that you are submitting and briefly +describe what it is. A committer will need to provide a descriptive log message +when committing your work. Providing a clear description here will help them. +

+Consider writing the Description and Summary text before you start entering +your patch report. You could save it in a local text file beforehand and +then copy-and-paste it when the time comes. +

+ +If this were a bug report, then it would need extensive description. +

+ +

3. Send the patch report

+Review your options, then press the Commit button. This will +add an entry to the bug database and email a report to the +cocoon-dev mailing list and a copy to you. Your submission will be +assigned a unique Bug Number which you can use to review its progress. +

+The next steps will show you how to attach your patch to the report that you +have just created ... +

+ +

4. Create an attachment of the actual patch

+You will be presented with a status screen saying that your bug report +was accepted and that email was sent to cocoon-dev mailing list. +

+Now you have a choice ... proceed to review your bug report by selecting the +link "Back to Bug #XXXXX". If you forgot to mention something, +then you can add more comments. From that screen, follow the link +"Create a new attachment". +Otherwise follow the link from this status screen to "Attach a file to +this bug". +

+ +

Specify the file to be uploaded

+Provide the local pathname to your patchfile, e.g. +/home/me/work/cocoon/patch/howto-bugzilla.tar.gz + +

+ +

Describe the attachment

+Provide a concise one line description, e.g. +Gzipped TAR archive with new docs and diffs + +

+ +

Specify the contentType of the attachment

+If it is a Gzipped TAR archive (*.tar.gz) or a .zip archive, then select +"Binary file (application/octet-stream)". +If it is just a single xml document, then select +"Plain text (text/plain)". +If the patch is just a single diff file, then select +"Patch file (text/plain, diffs)". +

+ +

5. Submit the attachment

+When you are ready, press the Submit button. As for Step 3, +you will be presented with a status screen saying that your attachment +was accepted and that email was sent to cocoon-dev mailing list. +

+ +

6. Be patient

+Now your patch will wait inside Bugzilla until one of the Cocoon committers +assigns the patch to their own email address and starts to process it to apply +it to the master CVS repository. As the registered owner of the Bug, you will +be sent an automatic email at each of these stages. +

+ +

7. Add more description or attachments if necessary

+Until the patch is applied by the committer and the Bug report is closed, you +can still add more to your bug report. However, only do this when +absolutely necessary because the patch should not be +changing while the committer is trying to commit it. If you just want to make +further changes, then it would be better to wait until your patch is +applied. Then you can make a new patch. Remember that the committer has full +veto and may decide to make some slight modifications to your patch. So it +is far better to wait. +

+ +

8. Adding subsequent patches to the same document or program

+If you want to make more patches to the same file, then please open a new Bug +rather than re-open the old one. After all, once the original patch is +applied by the committer, its corresponding Bug report is closed. +

+ +

Real World Extension

Contributing patches, in the form of documentation or code, is a vital way to give back to the Cocoon community. For example, you might consider contributing a timely patch in the form of a new FAQ, how-to, or tutorial. Or, you may also consider submitting a patch which updates Cocoon's existing user and developer guides.

+ +

Tips

+ +

Setting user preferences

+You can configure certain preferences, though the Bugzilla defaults work just +fine. +

+ +

Review the bugzilla documentation

+There are various explanations of terminology and procedures ... follow the +links should you need to know more. +

+ +

Search Bugzilla

+Bugzilla has a very powerful search interface. Now that you have a login +account, Bugzilla can remember customized queries which you can run with a +single click. +

+ +

References

+Bugzilla is at +http://issues.apache.org/bugzilla/ + +
+Helpful Bug Writing Guidelines are available directly from the +Bug entry interface. +

+ + + Propchange: forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.pdf?rev=193078&view=auto ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: forrest/site/docs_0_60/howto/bugzilla-patch/my-images/bugzilla-screen.gif URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/bugzilla-patch/my-images/bugzilla-screen.gif?rev=193078&view=auto ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_60/howto/bugzilla-patch/my-images/bugzilla-screen.gif ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: forrest/site/docs_0_60/howto/howto-asf-mirror.html URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-asf-mirror.html?rev=193078&view=auto ============================================================================== --- forrest/site/docs_0_60/howto/howto-asf-mirror.html (added) +++ forrest/site/docs_0_60/howto/howto-asf-mirror.html Wed Jun 22 22:36:19 2005 @@ -0,0 +1,396 @@ + + + + + + + +Generate an ASF mirrors page using interactive web form (v0.6) + + + + + + + + + +

+apache > forrest +

+ +

+ + +

0.60

+Overview +

+FAQs +

+Changes +

+Todo +

+Using Forrest +

+Upgrading to 0.6 +

+XML Validation +

+Menus and Linking +

+Searching +

+Default Skins +

+Skin Packages +

+Our Contract +

+Standards Compliance +

How-To

+Overview +

+Single Page +

Multi-Page

+Intro +

+Step 1 +

+Step 2 +

+Step 3 +

+With Images +

+Write a How-to +

Download mirror

+Create tab PDF +

Advanced Topics

+Building Forrest +

+Using DTD Catalogs +

+Sitemap Reference +

+Project sitemap +

+Sourcetype Action +

Reference docs

DTD documentation

+Overview +

+howto-v20 +

+faq-v20 +

+howto-v13 +

+faq-v13 +

Doc samples

+ This is documentation for past version v0.6 + (More)

+Font size: + + + +

Generate an ASF mirrors page using interactive web form

Use ihtml (interpreted html) to include html form elements + into a forrest-generated html page. For example, this enables building + automated download mirror pages for ASF project websites. +

+ This is documentation for past version v0.6 + (More)

+Intended Audience +
+Purpose +
+Prerequisites +
+Steps +
+

+ +

Intended Audience

Any Apache project that uses Forrest to generate their website + will need to have a mirrors page.
Also anyone interested in the use of ihtml to embed html form + elements into a generated Forrest page.

+ +

Purpose

All Apache projects use dynamically generated download pages + which determine the closest mirror and provide an interactive list of + the current alternative mirrors. + This HowTo describes the procedure to generate the template page + that is utilised by the mirrors.cgi script. The processed page + includes html "form" elements that are not included in the xdocs DTDs. +

This process has many exciting applications, beyond the scope of + this document. +

+ +

Prerequisites

Followed the documentation about + Making your + downloads mirrorable and + Apache Mirroring Information + . +
Established your ASF distribution space as described.
Already building your project website with Forrest.

+ +

Steps

+ +

Add the mirrors.cgi as a raw file

As explained in the mirrors document, there will be a two-line CGI + wrapper script at the top-level of your website called + mirrors.cgi +

Utilising the Forrest concept of raw un-processed content, + add the file as src/documentation/mirrors.cgi + (copy the Forrest project's + mirrors.cgi) +

+ +

Add the mirrors.ihtml to xdocs directory

This file contains the html content of your mirror page, including + the html form elements which drive the mirror selection. It also + contains the specific tokens that are interpreted by the mirrors.cgi + script to add the list of mirrors and select the closest. +

+ Add the file as src/documentation/xdocs/mirrors.html + (Use the Forrest project's + mirrors.html + as a template and edit it to suit.) +

+ +

Add a menu entry for Download

Add an entry to your site.xml navigation. For example ... +

+ <about label="About">
+  <index label="Index" href="index.html"/>
+  <license label="License" href="license.html"/>
+  <download label="Download" href="http://forrest.apache.org/mirrors.cgi"/>
+  <download_html href="mirrors.html"/><!-- so the page is part of a tab -->
+  ...

+ +

Cause the mirrors.ithml to be processed as an extra file

Forrest gathers the links that are to be crawled, by reading site.xml + and by finding any other internal links in the actual documents. + There is no link to mirrors.html because it is an extra file that needs + to be generated and skinned, but not linked in any way. +

The Cocoon command-line interface + (CLI) + to the rescue. Add an entry to your project's cli.xconf by copying the + default one from + $FORREST_HOME/context/WEB-INF/cli.xconf to your + src/documentation/conf/ directory (or wherever + ${forrest.conf-dir} points). Add the following entry ... +

+<uris name="mirrors" follow-links="false">
+  <uri type="append" src="mirrors.html"/>
+</uris>

+ +

Run 'forrest' to build your site

+ That is all that you need to do, Forrest will take care of it from + there. Run the 'forrest' command. The mirrors.html page + will be generated with the skin applied. +

+ +

Explanation of the process

Forrest automatically reads ihtml files and transforms the html source + to the forrest xdocs intermediate format. It mainly detects heading + elements (h1, h2, etc.) and converts them to "sections". The remainder + of the html elements are copied over as-is. With this technique the + html form elements are copied over to the output. +

+ + + Propchange: forrest/site/docs_0_60/howto/howto-asf-mirror.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_60/howto/howto-asf-mirror.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-asf-mirror.pdf?rev=193078&view=auto ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_60/howto/howto-asf-mirror.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: forrest/site/docs_0_60/howto/howto-howto.html URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-howto.html?rev=193078&view=auto ============================================================================== --- forrest/site/docs_0_60/howto/howto-howto.html (added) +++ forrest/site/docs_0_60/howto/howto-howto.html Wed Jun 22 22:36:19 2005 @@ -0,0 +1,483 @@ + + + + + + + +How to write a How-To (v0.6) + + + + + + + + + +

+apache > forrest +

+ +

+ + +

0.60

+Overview +

+FAQs +

+Changes +

+Todo +

+Using Forrest +

+Upgrading to 0.6 +

+XML Validation +

+Menus and Linking +

+Searching +

+Default Skins +

+Skin Packages +

+Our Contract +

+Standards Compliance +

How-To

+Overview +

Single Page

Multi-Page

+Intro +

+Step 1 +

+Step 2 +

+Step 3 +

+With Images +

Write a How-to

+Download mirror +

+Create tab PDF +

Advanced Topics

+Building Forrest +

+Using DTD Catalogs +

+Sitemap Reference +

+Project sitemap +

+Sourcetype Action +

Reference docs

DTD documentation

+Overview +

+howto-v20 +

+faq-v20 +

+howto-v13 +

+faq-v13 +

Doc samples

+ This is documentation for past version v0.6 + (More)

+Font size: + + + +

How to write a How-To

This How-To describes the steps necessary to write a How-To + document. Writing documentation is a valuable way to give back to the + community.

+ This is documentation for past version v0.6 + (More)

+Intended Audience +
+Purpose +
+Prerequisites +
+Steps +
- +Write the Overview +
- +Describe your Intended Audience +
- +State the Purpose +
- +List any Prerequisites +
- +Describe the Steps of your How-To +
- +Extend the Learning +
- +Summarize the Entire Process +
- +Additional Tips or FAQs +
- +References +
- +Submit via the project issue tracker +
- +Get some feedback +
+
+Extension +
+Frequently Asked Questions +
- +1 What is the difference between a How-To and a tutorial? +
- +2 What spelling convention should I follow? +
+
+Tips +
- +How-To dtd +
+
+References +

+ +

Intended Audience

Users who are ready to share their knowledge and experiences with the + community.

+ +

Purpose

These guidelines are based on successful how-to document structures + used by other open source projects with diverse author groups. Following + these tried and true guidelines will help to insure the effectiveness of + your work.

+ +

Prerequisites

How-To authors should have:

A unique How-To topic, related to using Forrest, which fulfills a + specific need. Check out existing How-Tos to find a niche for your work. + Consider posting your idea for the How-To to user mailing list, to make + sure another author's draft is not already in process.
A sufficient ability in English to write the FAQ. However, we would + rather that you just make a start, as the community can help to + fine-tune the document.
Copy this template document "howto-howto.xml" to be modified with + your own content as necessary.
An understanding of the How-To document structure. Just use this + template document and you will be safe. + Make sure you run 'forrest validate-xdocs' before + contributing your document.

Note

See the DTD documentation + which explains the document structure.

+ +

Steps

Here is how to proceed.

+ +

Write the Overview

An overview helps potential readers to determine quickly if a + particular How-To matches their interests or needs. In a few sentences, + summarize the main points of your How-To. Make sure to include any + critical definitions which will help readers evaluate the utility of + your How-To. Consider writing the overview last, after you have + completed all other sections.

+ +

Describe your Intended Audience

If your How-To is targetted at a specific audience, describe it here. + For example, potential readers will have different levels of skill using + Forrest. They will also bring different areas of expertise and + backgrounds to their How-To learning experience. When you clarify your + target audience up front, you will save all other readers time and + confusion.

+ +

State the Purpose

State the purpose of your How-To. Explain how the reader will benefit + by reading it. Give your reader an incentive or two to continue.

+ +

List any Prerequisites

Inform your reader about any required knowledge, configuration, or + resources they may need before stepping through your How-To. Assist them + in this preparation by linking to other useful resources on the Forrest + site or the web. Helping your readers to prepare increases the + likelihood that they will continue reading your How-To.

+ +

Describe the Steps of your How-To

In a precise, step-by-step approach, walk your reader through the + process. Make sure your reader can reproduce your intended result by + following your exact steps. Make the learning process efficient by + supplying sample code snippets or configuration details as + necessary.

+ +

Extend the Learning

Provide your reader with a few real-world examples of how the + techniques or capabilities gained from your How-To could be applied. + Reward the reader for successfully completing the How-To with a few + ideas about how it will pay off.

+ +

Summarize the Entire Process

In a few sentences, remind the reader what they have just learned. + This helps to reinforce the main points of your How-To.

+ +

Additional Tips or FAQs

In some cases, step-by-step instructions simply aren't enough. Use + this section to pass on any other tips or frequently asked questions. + Anticipating the needs of your readers will increase the overall success + of your writing effort.

+ +

References

Remember to acknowledge any third-party resources or individuals who + contributed to the development of your How-To. Consider providing links + for those motivated readers who want to learn more.

+ +

Submit via the project issue tracker

Create an attachment for your How-To document, and submit it via the + project issue tracker.

+ +

Get some feedback

When the committers have added your document then it will be + available for everyone to to build upon and enhance. Feedback will + happen via the mailing lists.

+ +

Extension

Solutions can be extended to cover many different problem domains. A + nearly unlimited number of potential How-To topics, from simple to + complex, are available right now, limited only by your imagination.

+ +

Frequently Asked Questions

+ +

1 What is the difference between a How-To and a tutorial?

The goal of a How-To is to help the reader to accomplish a specific + task with clear and consise instructions. While tutorials may contain + How-To-like instructions and content, they also include additional + background and conceptual content to help teach their readers higher + order concepts along the way. How-Tos are concerned about filling an + immediate, short-term need. Tutorials often provide long-term + knowledge which can be applied across a range of needs.

+ +

2 What spelling convention should I follow?

Use whatever spelling convention (American, British, etc.) that is + most intuitive to you.

+ +

Tips

+ +

How-To dtd

The document structure is likely to change soon. Please note that + this HOWTO page is likely to change as well.

+ +

References

This is not the first, nor will it be the last, How-To on writing + How-Tos. For other ideas and opinions on the matter, check out the + following sources.

Joel D. Canfield's How + to Write a How-To on evolt.org.
The Linux Documentation Project's HOWTO + index page provides many excellent How-To documents to inspire your + efforts.

+ + + Propchange: forrest/site/docs_0_60/howto/howto-howto.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_60/howto/howto-howto.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-howto.pdf?rev=193078&view=auto ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_60/howto/howto-howto.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: forrest/site/docs_0_60/howto/howto-pdf-tab.html URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-pdf-tab.html?rev=193078&view=auto ============================================================================== --- forrest/site/docs_0_60/howto/howto-pdf-tab.html (added) +++ forrest/site/docs_0_60/howto/howto-pdf-tab.html Wed Jun 22 22:36:19 2005 @@ -0,0 +1,520 @@ + + + + + + + +How to create a PDF document for each tab (v0.6) + + + + + + + + + +

+apache > forrest +

+ +

+ + +

0.60

+Overview +

+FAQs +

+Changes +

+Todo +

+Using Forrest +

+Upgrading to 0.6 +

+XML Validation +

+Menus and Linking +

+Searching +

+Default Skins +

+Skin Packages +

+Our Contract +

+Standards Compliance +

How-To

+Overview +

+Single Page +

Multi-Page

+Intro +

+Step 1 +

+Step 2 +

+Step 3 +

+With Images +

+Write a How-to +

+Download mirror +

Create tab PDF

Advanced Topics

+Building Forrest +

+Using DTD Catalogs +

+Sitemap Reference +

+Project sitemap +

+Sourcetype Action +

Reference docs

DTD documentation

+Overview +

+howto-v20 +

+faq-v20 +

+howto-v13 +

+faq-v13 +

Doc samples

+ This is documentation for past version v0.6 + (More)