Roadmap

[Matt Todd]

> Our roadmap for Net::LDAP 1.0 is to gain full *client* compliance with the most recent LDAP RFCs (4510–4519, plus portions of 4520–4532).

Aside from this statement found in the README, I haven't seen any recent discussion of a roadmap for the project.

I'd like to share what I think makes sense for the roadmap to kick off the discussion of whether we should have something formal, where it would live, who should maintain it and how, etc, if at all.

Referring back to the statement about 1.0 above, I fully support targeting compliance with the proposals. One example is filter handling; according to the spec, "(|(uid=one)(uid=two)(uid=three))" is valid, but `Net::LDAP::Filter` is hardcoded, not only for the out-of-date RFC 2254, but specifically for left/write pairs producing "(|(|(uid=one)(uid=two))(uid=three)" needlessly. This is not the only case, but it's one I've seen in the wild a number of times.

Code quality and style is all over the place. There's a lot of repeated stanzas (like the connection handling repeated for every operation) that could easily be refactored out. Many functions are huge and complex, poorly commented, black boxes which hampers troubleshooting and debugging, especially in production systems. Literals are littered throughout the library, masking intention/context where a constant would be more appropriate.

There are also some ways to encourage and improve performance, yet the library works against that. Timeouts could be added, and making `open { ... }` work consistently and make sense (there are rough edges there that I'm still uncovering).

The testing situation is a little haphazard. Modern CI environments can allow us to automate setting up, for instance, OpenLDAP to run tests against. While https://github.com/github/github-ldap currently uses Ladle (https://github.com/NUBIC/ladle) to boot an ApacheDS instance in-process to test with, I'm planning on replacing or pairing that with an OpenLDAP CI environment. And maybe Azure AD will make CI tests with ActiveDirectory a possibility as well (though I can't say).

I'd like to keep this library very practically focused and scoped. Following the spec will result in a more usable and portable library, while contradicting the spec is not an option (nor does it make any sense to deviate). Productive development, for experienced and new developers alike, should be the goal. We should be aiming to do just that, whether that's better documentation or tooling such as automated testing harnesses. We can explore ways to empower integrators better by answering the question "How are people abusing the library? What simple mistakes are they making? How can we help them learn and get better feedback, sooner?"

[Jerry Cheung]

+1 I think there are many easy tasks to complete as far as cleanup goes. Here are the areas I'd like to see before a 1.0. This isn't a complete list, and doesn't indicate priority, but I wanted to list them out for feedback.

Maintenance

- triage and clear out the existing issues and pull requests. Many of them are out of date and can be closed; We can ask the submitter if it's still a valid issue.

- consistent code formatting

- consolidate test frameworks. More on that later.

- remove unused files

- audit gem dependencies for whether we still need them, and for versions

- add ruby 2 series and ruby-head to build matrix

Documentation

- audit public rdoc for params and return values. Refer to specific sections of the RFC where applicable for easier reference to original spec.

- update History.rdoc (it hasn't been since 0.5.0)

- add documentation for maintainers for steps to releasing a version (example)

- update http://rubyldap.com

- rename Hacking.rdoc to Contributing.md and audit

Refactoring

The current Net::LDAP and Net::LDAP::Connection objects handle the bulk of the work. These files are large and difficult to reason through. I'd like to slowly extract objects to make unit testing easier, and to minimize changes to classes that don't need them. The first candidate for this is a SearchRequest object to encapsulate the setup and state needed for executing a search. I don't plan on building a deep class hierarchy up front, but rather extracting concerns one by one as needed.

Testing

I propose we move towards Minitest as the only test framework. The immediate benefit is removing rspec and flexmock as dependencies. The more subjective benefits are flatter test cases (deeply nested rspec contexts are hard to follow), plain old ruby objects, and easy to remember assertions.

+1 on integration tests for various LDAP servers. This will be a good place to reproduce and document edge cases and regressions as well.

Release process

What is the current process for building a release gem? I noticed that hoe was a dependency, but is it still being used? I'd like to move towards using plain "gem" tools for building and releasing future versions for simplicity. This will require an audit of the gemspec. Do we still need Manifest.txt?