Contributing Modules
If you are interested in contributing a module, we recommend the following steps.
Submitting Initial Code
Look at this site's list of modules to see
if someone else has already written something that does what you want. Search the Plugin Portal and
ask on the NetBeans developer mailing list (
-
see mailing lists for details of subscribing) or search our our plugin portal to see
if anyone else has already begun work on such a module, or has some ideas,
or test code, etc.Assuming that no one else has anything solid, please write a
"first draft" of the module that at least compiles and does something
recognizable. You probably will not draw much interest before this
stage. Create some kind of archive of your sources, and perhaps also
an initial binary build or
NBM
to make it easy for others to try out your new module quickly. A ZIP
(or JAR) file is the conventional format for the archive you create,
as it can be read on all systems.
Remember to put some license notice or at least a copyright on
whatever text files you are including; if you intend the module to be
hosted in CVS, only CDDL is acceptable, see below. If you just want to make your existing
module available quickly to people to try out, submit it to our plugin portal, and skip the
rest of this page. If you have an existing CVS (or RCS) repository with module
sources and would like to have this history preserved, please include
the *,v files in addition to the plain sources. Make sure you have an account on the site. Anyone can
join,
you just need an email address. If this is your first code submission to netbeans, you must fill in
a Contributor Agreement - see the CA
Policy page for more info. No contribution can be accepted until a
CA is completed. Go to the
file upload area
on contrib.netbeans, where your module will be housed at least
temporarily. Click Suggest a Download. Browse to your
contribution archive. Provide a short description (one sentence)
summarizing what the contribution is about. Make sure Public is
checked (it is not by default), and click
Upload File to send it to the site.
The contrib.netbeans catch-all project should
only be used if your contribution does not easily fit
into any obvious existing project. If you really want to be working on
an existing project - for example, you want to integrate a new version
of the Tomcat server and you see that there is already a
tomcatint.netbeans project - use that project
instead: suggest a file upload, ask for permissions on that project,
and so on. While you will be able to see your contribution with pending
status, using the above URL for the file upload area, it will be
hidden from other users initially. A moderator must approve the upload
first. Please wait a day or two for it to be accepted; normally a
moderator will tell you when it is approved. Send a message to the NetBeans developer list
,
to let people know that you have submitted something, and mention the
address where it can be download from. Include a rough description of
what the purpose of the submission is, and ask for feedback.
Please do not send your sources to
nbdev; that is what the file upload is for. If you like, you can submit revised or expanded contributions
later using the same process. Code contributed in this way is expected to be short-lived: you
just want other people to see it and comment on it. You might want to
let others work on the code while it is still in an experimental
stage. If this is true, you can work with it in CVS. Go to the
membership request
page for contrib.netbeans and request the Developer role.
Again, you may need to wait a day or two for approval. When approved,
you may check out the contrib CVS module from
contrib.netbeans using your site login; make a new
subdirectory for your sources; and commit your source code there.
Only CDDL-licensed code may be committed. Please be
careful not to interfere with other people's scratch code areas, or
check in unreasonably large files, etc. Other people who wish to work
on your code with your permission may also request the developer role
and begin using CVS to make edits. contrib.netbeans may also be used to submit temporary
proposals or other documents not applicable to existing projects. Use
the
contrib.netbeans document list
servlet to upload them and make them viewable until they find a
permanent home. You may request the Content Developer role
for this project if you need to add a lot of documents and do not wish
to wait for approval each time. As the submitter of a contrib.netbeans project, feel free
to use Issuezilla in this component to file tasks for yourself. Users
may file bugs here too, but you will need to look for them yourself:
for technical reasons, it is impractical to add subcomponents for
every contribution. Subscribe to
to be sure.
Getting a Real Project
contrib.netbeans is only suitable for
temporary or offhand code submissions: either you are just
starting work on a module and are not yet sure if it will come to
anything; or you wrote something cool and want to share it with
others, but it is small and you have no plans to maintain it
permanently. No code in this project may be used as part of a
NetBeans distribution, or even be included in a development build or
placed on the beta- or stable-level update center! If you want code to
be taken more seriously, it will need to live in a proper project.
Often a good home for your code already exists. Take a look at
existing projects on netbeans to try to find a sensible match.
Your module could live in a subdirectory of one of these in CVS, for
example, while it stabilizes and grows.
But if your code is really new stuff, you will probably want a new
project. Here's how to do it.
Send a request to have a new module project hosted on the site
to Be sure to mention the desired project name -
typically a brief but descriptive phrase without punctuation or
capital letters, e.g. javadoc or
debuggerjpda or archivesupport - which will
be used for the website domain, the CVS directory, and so on.
Assuming there is no particular reason to refuse, the CVS/site
administrator will make a new project for you, and make you the
project owner. Be prepared to wait at least a day here, to make sure
list members have a chance to object against the proposed module or
suggest something different. This new project will come with its own CVS module directory,
mailing lists, bug category, web space, etc. You will be the owner of
this area and can administer it as you like, including granting other
people access to it. Log onto the administrative pages and set it up
as you like: make sure you are logged into the site, go to your
module's home page, and use the links such as Admin,
Members, etc. that you should find at the top of the
page. In order to be hosted on netbeans, a project should be licensed under the
Common Development and Distribution
License.
Ask on
if you think this is not reasonable or possible for you. Non-CDDL
licenses such as GPL cannot be hosted on netbeans, but they could
be hosted elsewhere and linked to from netbeans) Dual-licensed
sources, such as CDDL plus GPL or CDDL plus BSD, are not permitted, only
straight CDDL. All source files, including *.java as well
as textual resources like *.properties, should be marked
with the CDDL notice before being placed in CVS. It is not permitted to
keep anything but CDDL-marked sources in netbeans CVS, including
even innocent-sounding things like Apache binary libraries or sources.
Remember you
cannot license something you did not write yourself unless you have
explicit permission from the real author. If this is your first code submission to netbeans, you must fill in
a Contributor Agreement - see the CA
Policy page for more info. No contribution can be accepted until a
CA is completed. Check your code into CVS in the provided area and you are ready
to continue work and invite others to help! You can create and modify your project's web pages using CVS.
Please check the
module website guidelines
for some
pointers on setting up your module's website. Provide build and install instructions in your web area. In
most cases this will be a
standard Ant script.
You may want to put stable binaries of the module up for download on
your web pages to make it easier for people to try it (see the
Files link on your module home page). You can make your module available on the Auto Update center or
even part of the regular distribution of NetBeans if the quality of
your code
satisfies common requirements. If your module provides functionality to other modules using
some kind of API, you should follow the
versioning policy.
Remember that anyone can write a NetBeans module, whether hosted on
this site or not, using the Open APIs.
After building the module JAR files, these can be distributed however you
like, in source or binary form; anyone running the IDE can install them just
by right-clicking on the Modules node and selecting the desired JAR or NBM file.
Moderator Responsibilities
The site has a few moderators who are responsible for ensuring
that the contribution process is pushed forward smoothly and for
helping new contributors understand what is needed from them. Here are
a few things moderators should do to look for contributions and help
make them happen.
Accepting contrib.netbeans uploads
Watch for people on and other lists who seem to
be suggesting contributions - give them encouragement and point them
to this guide.Make sure you are
listed
as a project owner of contrib.netbeans. - Accept reasonable uploads to
contrib.netbeans as soon as
you see them.
Be careful about intellectual property when accepting
contrib.netbeans file download suggestions. It is not a requirement that
contributions here be under the CDDL; they could be GPL or
public-domain, so long as this is clearly admitted in the message. But
messages containing mis-licensed sources, e.g. files which
might have been taken from various sources without proper attribution,
should be rejected.
Examples: an enormous word list named dictionary.txt with
no explanation is probably stolen from somewhere, since the module author
is not likely to have compiled it personally; public DTDs and other
standards in code form are also generally not personally written by
the module author, and typically carry some special copyright or even
terms of use.
Sources derived from the JDK or otherwise
controlled in terms of redistribution should never be accepted. When
rejecting download because they might be legally dangerous, be sure to
include a comment to the sender as
explained in the admin interface, and let the sender know
what would need to be done for you to accept the contribution. It is your responsibility to confirm that the contributor has
filled in and submitted a Contributor Agreement. If they have,
they will be listed. Their contribution cannot be accepted
until they have done this - the form and further info are available.
When files are in fact accepted, remind the contributor to send
a message to announcing their existence. Accept requests for the Developer role on contrib.netbeans,
provided the requestor either already has this role elsewhere on the
site, or has demonstrated some sort of seriousness, typically by
submitting and having accepted a file upload full of code. Make sure
the submitter understands how to check out from contrib.netbeans
CVS, make a new subdirectory to work in, and commit without affecting
nearby files. Periodically search for unassigned issues in
contrib.netbeans and assign them to the proper owners.
Accepting new project requests
If a message is sent to requesting a new
project, and reasonable code is already available somehow on
contrib.netbeans,
and the message includes either a requested project name or an actual SourceCast
new-project request, make sure there is nothing technical preventing
the new project from being created (such as unsolved license issues -
only CDDL is acceptable - or confusion over the project name or scope).
If something looks unclear, ask on and CC the
contributor. If it looks OK, reply to saying that
as a moderator you will make this project in a day or so if there are
no objections. Before the new project owner can commit any code to their new
project, remember to confirm that they have submitted a Contributor
Agreement form. If they have, they will be listed=. A
contribution cannot be accepted until they have done this - the form
and further info are available.
Some contributions in fact can be best treated as additions to
existing projects. For example, Jeff Keyser's HTTP Javadoc filesystem
was a comparatively small block of code that made sense incorporated
into the existing Javadoc support module. Even if it seems a good idea
to make literally distinct modules as far as the IDE is concerned, it
is straightforward to keep several modules under one SourceCast
project - see for example the apisupport or
web projects which contain several modules apiece - since
they can split or share CVS, bug/issue, and web space flexibly.
Whenever this seems to be the case, try to avoid creating new
projects, and encourage cooperation between the owner of the existing
project and the new contributor. The site moderator is responsible
only for establishing that a contribution is of this sort and that the
existing project owner and the new contributor agree to work together.
After that point, the project owner has responsibility for physically
accepting the code, making the new contributor a developer on the
project, and so on. If at least 24 hours have passed since a request for a new project
that was technically in order, without any objections or suggestions
for changes in plans by the community on , a site
moderator should make (or approve) the project accordingly. If there
has been some mailing-list discussion expressing doubt whether a new
project should be created, a moderator should wait a while longer for
a consensus to emerge from the community, rather than rush into it.
Most projects are accepted without debate soon after 24 hours have
passed (either after little response on, or
positive or curious responses).A project can be made or accepted by someone with domain
privileges on the site using the SourceCast administrative interface.
When creating a project, a moderator should attend to the following
details:
Send email to the new project owner informing him that the project
has been created. Normally the owner should have already made himself
a SourceCast account, otherwise the moderator can make him an account
and also send username/password information. Respond to the project request on indicating
that it has been accepted.CC to make sure the contribution is
mentioned in the next newsletter.Submit a pending news item on netbeans. Make sure Jack Catchpoole (or ) are informed of the new project so they can
set up initial www/ files and maybe add the project to
a master list of projects on the site. It is enough to CC them on
some other message.Make sure Jan Chalupa (or some Issuezilla administrator) is
notified also of the new project to ensure that Issuezilla is properly
set up. It is enough to CC him on some other message. Give some pointers to the new project owner about resources
available to him when administering his module: e.g. that CVS is ready
and how to check into it; the existence of for
infrastructure questions; existence of conventions for build scripts;
the web guide for creating project web pages; SourceCast
administrative features available to him when logged in to the site;
the development resources index for
miscellaneous things. (Here is an
example message
of this type you could use for hints.)If uploading of CVS history files was requested, work with
CollabNet to ensure that this happens. Filing an Issuezilla request
against www and assigning to may be the best
approach (CC everyone relevant). If you want to make the module visible to others, ask to add your
module to CVSROOT/modules. Filing an Issuezilla TASK against "www" and
"netbeans CVS" is the best approach (CC and
). If you know how to make a patch for CVSROOT/modules,
attach it to the issue.
|
|
