Documentation preparation for version 0.2 release.

Hacking.rdoc

@@ -1,16 +1,59 @@
 = Hacking Net::LDAP
 
-We welcome your contributions to Net::LDAP. To increase the chances of your
+We welcome your contributions to Net::LDAP. We accept most contributions, but
-patches being accepted, we recommend that you follow the guidelines below:
+there are ways to increase the chance of your patch being accepted quickly.
 
-1. Your code should be formatted like the rest of Net::LDAP. We use a text
+== Licensing
-   wrap of 76 - 78 characters, especially for documentation contents.
+
-   Operators should have spaces around them, method definitions should have
+Net::LDAP 0.3 and later will be licensed under an MIT-style license; any
-   parentheses around arguments. Keep the indentation as flat as possible.
+contributions after 2010-04-20 must be under this license to be accepted.
-2. Your changes should be well-documented and described.
+
-3. You must provide rspec tests for any new or changed features. Rspec has
+== Formatting
-   been chosen as the way forward for tests.
+
-4. You should provide LDIF data for importing into LDAP servers so that the
+* Your patches should be formatted like the rest of Net::LDAP.
-   changes can be tested <em>in situ</em> with more than one real LDAP
+* We use a text wrap of 76–78 characters, especially for documentation
-   server.
+  contents.
-5. You should have tested your changes against a real LDAP server.
+* Operators should have spaces around them.
+* Method definitions should have parentheses around arguments (and no
+  parentheses if there are no arguments).
+* Indentation should be kept as flat as possible; this may mean being more
+  explicit with constants.
+
+== Documentation
+
+* Documentation: net-ldap[http://net-ldap.rubyforge.org/]
+
+It is very important that, if you add new methods or objects, your code is
+well-documented. The purpose of the changes should be clearly described so that
+even if this is a feature we do not use, we can understand its purpose.
+
+We also encourage documentation-only contributions that improve the
+documentation of Net::LDAP.
+
+== Tests
+
+The Net::LDAP team uses RSpec for unit testing; all changes must have rspec
+tests for any new or changed features.
+
+Your changes should have been tested against at least one real LDAP server; the
+current tests are not sufficient to find all possible bugs. It's unlikely that
+they will ever be sufficient given the variations in LDAP server behaviour.
+
+If you're introducing a new feature, it would be useful to provide LDIF data
+for importing into LDAP servers for testing.
+
+== Development Dependencies
+
+Net::LDAP uses several libraries during development, all of which can be
+installed using RubyGems.
+
+* *hoe*
+* *hoe-git*
+* *archive-tar-minitar*
+* *metaid*
+
+== Participation
+
+* RubyForge: net-ldap[http://rubyforge.org/projects/net-ldap]
+* GitHub: RoryO/ruby-net-ldap[http://github.com/RoryO/ruby-net-ldap/]
+* Group: ruby-ldap[http://groups.google.com/group/ruby-ldap]

History.txt

@@ -1,4 +1,6 @@
-=== Net::LDAP NEXT / 2010-__-__
+=== Net::LDAP 0.2 / 2010-04-__
+* Added a document describing how to contribute to Net::LDAP most effectively.
+* Preparing for a license change for Net::LDAP in the next release.
 * SSL capabilities will be enabled or disabled based on whether we can load
   OpenSSL successfully or not.
 * Moved the core class extensions extensions from being in the Net::LDAP
@@ -38,7 +40,7 @@
 === Net::LDAP 0.1.1 / 2010-03-18
 * Fixing a critical problem with sockets.
 
-=== Net::LDAP 0.1.0 / 2010-03-17
+=== Net::LDAP 0.1 / 2010-03-17
 * Small fixes throughout, more to come.
 * Ruby 1.9 support added.
 * Ruby 1.8.6 and below support removed. If we can figure out a compatible way

README.txt

@@ -2,48 +2,54 @@
 
 == Description
 
-Pure Ruby LDAP library.
+Net::LDAP for Ruby (also called "net-ldap") is a pure-Ruby LDAP support
+library that has been tested against several modern servers, including
+OpenLDAP and Active Directory. It supports most LDAP client features and
+a subset of server features.
+
+LDAP (Lightweight Directory Access Protocol) is an Internet protocol for
+accessing distributed directory services. LDAP is often used to provide
+access and authentication to networked services.
+
+The current release is mostly compliant with RFCs 2251–2256, 2829–2830,
+3377, and 3771. Our roadmap for Net::LDAP 1.0 is to gain full
+<em>client</em> compliance with the most recent IETF LDAP RFCs
+(4510–4519, plus portions of 4520–4532).
+
+=== Notice of Impending License Change
+
+In the next release of Net::LDAP (0.3), we will be changing the license
+to an MIT-style license.
 
 == Where
 
-=== Issues & Project Homepage
+* RubyForge: net-ldap[http://rubyforge.org/projects/net-ldap]
+* GitHub: RoryO/ruby-net-ldap[http://github.com/RoryO/ruby-net-ldap/]
+* Group: ruby-ldap[http://groups.google.com/group/ruby-ldap]
+* Documentation: net-ldap[http://net-ldap.rubyforge.org/]
 
-http://rubyforge.org/projects/net-ldap
+== Requirements
-
-=== Code
-
-http://github.com/RoryO/ruby-net-ldap/
-
-== FEATURES/PROBLEMS
-
-The Lightweight Directory Access Protocol (LDAP) is an Internet protocol for
-accessing distributed directory services.
-
-Net::LDAP is an LDAP support library written in pure Ruby. It supports most
-LDAP client features and a subset of server features as well.
-
-* Standards-based (going for RFC 4511)
-* Portable: 100% Ruby
-
-== SYNOPSIS
-
-See Net::LDAP for documentation and usage samples.
-
-== REQUIREMENTS
 
 Net::LDAP requires Ruby 1.8.7-compliant interpreter or better.
 
-== INSTALL
+== Install
+
+Net::LDAP is a pure Ruby library. It does not require any external
+compiled libraries.
 
-Net::LDAP is a pure Ruby library. It does not require any external libraries.
 You can install the RubyGems version of Net::LDAP available from the usual
 sources.
 
-* gem install net-ldap
+  gem install net-ldap
 
-Simply require 'net/ldap'.
+Simply require either 'net-ldap' or 'net/ldap'.
 
-== CREDITS
+For non-RubyGems installations of Net::LDAP, you can use Minero Aoki's
+{setup.rb}[http://i.loveruby.net/en/projects/setup/] as the layout of
+Net::LDAP is compliant. The setup installer is not included in the
+Net::LDAP repository.
+
+== Credits
 
 Net::LDAP was originally developed by:
 
@@ -58,13 +64,13 @@ Contributions since:
 * Dimitrij Denissenko dimdenis@rubyforge.org
 * "nowhereman" on GitHub
 
-== LICENSE
+== License
 
 Copyright (C) 2006 - 2010 by Francis Cianfrocca and other contributors.
 
-Please read the file LICENSE for licensing restrictions on this library. In
+Please read the file LICENSE for licensing restrictions on this library.
-the simplest terms, this library is available under the same terms as Ruby
+In the simplest terms, this library is available under the same terms as
-itself.
+Ruby itself.
 
-Available under the same terms as Ruby. See LICENSE in the main distribution
+Available under the same terms as Ruby. See LICENSE in the main
-for full licensing information.
+distribution for full licensing information.

Rakefile

@@ -33,6 +33,7 @@ Hoe.spec PKG_NAME do
   self.description = paragraphs_of(self.readme_file, 2..2).join("\n\n")
 
   extra_rdoc_files << MANIFEST.grep(/\.rdoc$/)
+  extra_rdoc_files.flatten!
 
   extra_dev_deps << [ "archive-tar-minitar", "~>0.5.1" ]
   extra_dev_deps << [ "hoe-git", "~>1" ]