Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Encourage PrePAN #40

Merged
merged 2 commits into from

2 participants

@dagolden

As discussed in Lancaster, these commits revise the "About PAUSE" page to more strongly encourage PrePAN. It also adds a PrePAN plug to the welcome email.

dagolden added some commits
@dagolden dagolden Downplay module registration on the "about PAUSE" page
This encourages people to use PrePAN for feedback about module
ideas and revises some related sections to make them briefer and clearer.
997393e
@dagolden dagolden mention PrePAN in welcome email 06aaa57
@andk andk merged commit 06aaa57 into andk:master
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 17, 2013
  1. @dagolden

    Downplay module registration on the "about PAUSE" page

    dagolden authored
    This encourages people to use PrePAN for feedback about module
    ideas and revises some related sections to make them briefer and clearer.
  2. @dagolden
This page is out of date. Refresh to see the latest.
Showing with 72 additions and 81 deletions.
  1. +68 −81 htdocs/04pause.html
  2. +4 −0 lib/pause_1999/edit.pm
View
149 htdocs/04pause.html
@@ -13,7 +13,8 @@
<li><a href="#registering">Registering as a developer</a></li>
<li><a href="#menu">Visit PAUSE</a></li>
<li><a href="#duties">Your duties, the basics, traps</a></li>
- <li><a href="#namespace">Register your namespace!</a></li>
+ <li><a href="#before">Before you upload</a></li>
+ <li><a href="#comparison">PAUSE vs. CPAN vs. search engines</a></li>
<li><a href="#takeover">Taking over</a></li>
<li><a href="#readme">README</a></li>
<li><a href="#version">$VERSION</a></li>
@@ -114,37 +115,44 @@
<li> Respect the namespace of others</li>
</ol>
-<h3><a id="namespace" name="namespace">Register your namespace!</a></h3>
-
-<p><b>Please,</b> talk to other people (
- <a href="http://prepan.org/">PrePAN</a>,
- find your local <a href="http://www.perl.org/community.html">community</a>,
- comp.lang.perl.modules,
- modules@perl.org
- or any <a href="http://lists.perl.org">mailing list</a>
- that fits your problem domain)
-before you decide upon the namespace you're going to use for your
-module. Usually it's not considered the perl way to have bureaucratic
-conventions, but when it comes to namespace pollution, there is the
-need of coordination. Just like the InterNIC has to care for unique
-names for internet hosts, somebody has to (sort of) guarantee
-uniqueness, consistency, and sanity of module names. <a
-href="http://search.cpan.org/">search.cpan.org</a> is the place where
-all currently uploaded modules can be found and the email address
-<b>modules@perl.org</b> is an alias for a hand full of experienced
-volunteers who try to give advice for the appropriate namespace for
-your modules.</p>
-
-<p>Please consider the namespace you're going to occupy with all due
-sensitivity. Discuss it in the appropriate fora. Read what the
-<code>perlmodlib</code> manpage has to say about this. Reading these
-sections carefully will help you and us to greatly improve the
-usefulness of the CPAN and avoid cumbersome renaming at a later
-date.</p>
-
-<blockquote> Also: think carefully and honestly whether your module
-would be better off if it were integrated as an option into an already
-existing module. Sometimes it is for the best to put aside personal
+<h3><a id="before" name="before">Before you upload</a></h3>
+
+<p>Before uploading a new module to CPAN, please carefully consider:</p>
+
+<ul>
+ <li>What name you plan to use for your module</li>
+ <li>How your module relates to similar modules</li>
+</ul>
+
+<p>
+Choosing a good name is important if you want people to find your module
+on CPAN and understand (from the name alone) what it does.
+</p>
+
+<p>
+Likewise, there are so many modules already on CPAN that it's a good idea
+to be sure that your module is doing something new or at least different
+(and hopefully better) than something already on CPAN. Search for similar
+modules on <a href="http://metacpan.org">metacpan.org</a> or
+<a href="http://search.cpan.org/">search.cpan.org</a>.
+</p>
+
+<blockquote>
+<p><strong>If you have never uploaded a module to CPAN before (and even if you have),
+you are strongly encouraged to get feedback on
+<a href="http://prepan.org/">PrePAN</a></strong>.</p></blockquote>
+
+<p><a href="http://prepan.org/">PrePAN</a> is a site dedicated to discussing ideas for CPAN modules with other
+Perl developers and is a great resource for new (and experienced) Perl
+developers. You can also consider discussing your ideas in other local
+<a href="http://www.perl.org/community.html">community groups</a> or
+online community sites like <a href="http://www.perlmonks.org/">Perl Monks</a>.
+
+
+<p>
+<strong>Also: think carefully and honestly whether your module
+would be better off if it were integrated into an already
+existing module.</strong> Sometimes it is for the best to put aside personal
glory and join a collaborative effort: Perl itself is a good example
of this. Contact the author of an existing module and ask whether your
new features would fit into his framework. Even if you in the end
@@ -152,45 +160,26 @@
your 'competition', that is, know all the similar modules and the
features they offer. Maybe you can learn from them, maybe you can help
the users of your module better by giving them an overview about
-similar modules.</blockquote>
-
-<p>And please do consult the archives of modules@perl.org before you
-post a module proposal. The fulltext search capabilities of the
-archive should help you to find similar suggestions and contact
-addresses. modules@perl.org is low volume, so your search in the
-archive is quite targetted. <b>modules@perl.org</b> is not a mailing
-list. Please do not try to subscribe. We do not want to establish yet
-another perl mailing list. If we encounter hot topics, we move the
-discussion to the appropriate mailing lists. The traffic on
-<b>modules@perl.org</b> is archived at <a
+similar modules.
+</p>
-href="http://www.nntp.perl.org/group/perl.modules/"
- >http://www.nntp.perl.org/group/perl.modules/</a>.
+<h3><a id="comparison" name="comparison">PAUSE vs. CPAN vs. search engines</a></h3>
+<p>
+Authors upload new modules to PAUSE, which is responsible for inspecting,
+validating and indexing uploads. PAUSE unwraps the upload and scans the source code
+(namely all <code>*.pm</code> files) for package declarations. In order for
+a module to be indexed, the submitting author must be the owner or an authorized
+maintainer for every package namespace found (unless the namespace is new, in
+which case the uploading author becomes the owner of it).
</p>
-<p>When you're done with all your preparations, considerations, and
-investigations, visit the PAUSE and fill in the form for a new module
-namespace. Take your time filling in the rationale of the module
-proposal. Consider, your form will be posted to modules@perl.org too,
-so other developers will probably stumble over this description many
-years later. The better the description, the better the chances that
-your module will actually be used.</p>
-
-<p>You need not wait for approval. You can upload anytime, even before
-you fill in the form. Uploading and registering are only loosely
-coupled.</p>
-
-<p>The indexes that are maintained automatically on CPAN all double check
-if the module names that are used in the uploaded packages are
-registered. The indexer unwraps all packages and scans the source code
-(namely all <code>*.pm</code> files) for package declarations. You run
-the <b>risk of being ignored</b> by the index generator if you do not
-talk to the PAUSE maintainers about the namespace you are
-using.</p>
-
-<p>A frequent cause for confusion is the relation between CPAN itself
-and search.cpan.org. The PAUSE/CPAN indexer produces the files</p>
+<p>
+After a module is uploaded to PAUSE, it propagates to
+<a href="http://www.cpan.org/">www.cpan.org</a> and dozens of other CPAN mirrors
+around the world. PAUSE also creates a number of index files used by CPAN clients
+like CPAN(.pm), CPANPLUS and cpanminus:
+</p>
<pre>
authors/00whois.html
@@ -201,20 +190,20 @@
modules/06perms.txt.gz
</pre>
-<p>These are the ones CPAN{,PLUS}.pm are using to find the
-downloadables and <a href="http://search.cpan.org">search.cpan.org</a>
-to mark releases as unauthorized.</p>
+<p>
+CPAN search engines like <a href="http://metacpan.org">metacpan.org</a> and
+<a href="http://search.cpan.org/">search.cpan.org</a> use these indexes
+and other heuristics to allow Perl developers to find modules that
+interest them.
+</p>
-<p><a href="http://search.cpan.org">search.cpan.org</a> has its own
-indexer which has to satisfy other demands. It is based on the
-PAUSE/CPAN indexes but it is being changed more often because of the
-specific needs search.cpan.org has.</p>
+<p>If you have questions about these, be sure to send them to the right place:</p>
-<p>Questions regarding the PAUSE/CPAN indexer should be sent to
-modules@perl.org. The feedback addresses for issues with
-search.cpan.org are given at <a
-href="http://search.cpan.org/">search.cpan.org</a>. Click the
-<i>feedback</i> link there.</p>
+<ul>
+ <li>PAUSE and CPAN mirroring: modules@perl.org</li>
+ <li>search.cpan.org: cpansearch@perl.org</li>
+ <li>metacpan.org: Submit questions via the <a href="https://github.com/CPAN-API/metacpan-web/issues">metacpan bug tracker</a></li>
+</ul>
<h3><a id="takover" name="takeover">Taking over</a></h3>
@@ -310,8 +299,6 @@
<p>Good luck and thanks for stepping up.</p>
-
-
<a id="conventions" name="conventions"></a><!-- older anchor name -->
<h3><a id="readme" name="readme">README</a></h3>
View
4 lib/pause_1999/edit.pm
@@ -2447,6 +2447,10 @@ If you need any further information, please visit
\$CPAN/modules/04pause.html.
If this doesn't answer your questions, contact modules\@perl.org.
+Before uploading your first module, we strongly encourage you to discuss
+your module idea on PrePAN at http://prepan.org/ to get feedback from
+experienced Perl developers.
+
Thank you for your prospective contributions,
The Pause Team
};
Something went wrong with that request. Please try again.