Skip to content

Latest commit

 

History

History
92 lines (59 loc) · 3.56 KB

HACKERS.mdown

File metadata and controls

92 lines (59 loc) · 3.56 KB
Raw

So you wanna hack on Nimbus?

Nimbus follows one principle above all others:

        Nimbus may only grow if its documentation grows at the same rate, or faster.

By this principle, any new feature added to Nimbus must be documented. Where possible, examples should be provided. When necessary, architectural explanations must be referred to.

The next most important principle is a subset of the above:

          Nimbus may only grow if its unit tests grow at the same rate, or faster.

Any new method should include unit tests that run automatically when Nimbus is built for deployment. All unit tests must pass before a new feature may be included in Nimbus. Classes and objects must be designed in such a way that they may be independently tested.

Taking on Tasks

If you would like to help out with the development of Nimbus, the easiest way to start is to check out the Grab Bag tasks on Github:

https://github.com/jverkoey/nimbus/issues?milestone=5&sort=created&direction=desc&state=open

Adding New Features to Nimbus

If you would like to add a new feature to Nimbus take a moment to consider the following questions:

  • Has the feature already been built and open-sourced by someone else?
    • Does it have all of the features you'd like to see?
    • Is it well documented?
    • If the answers to the above are YES, then it's probably not a good feature to build it for Nimbus. Consider either writing a guide for integrating it with Nimbus or seeing whether it makes sense to add the feature as a third-party feature.
  • Are you ok with open sourcing your code?
    • If you work for a company, consult with your manager and/or legal team to ensure that it's ok for you to contributing code to an open source project. Nimbus uses the Apache 2.0 license.

Creating the Feature

All Nimbus features are contained within the src directory in separate directories with the following structure:

src       - all of the feature's source code
lib       - code that is only used to build the feature as a static library
unittests - all unit test code
resources - any resources the feature might require (in bundles for simplicity, usually)

Once you've set up the directory structure for your feature, add a new static library target to the Nimbus root project and add the necessary files to the target.

Documentation

Nimbus documentation is generated using a tool called Doxygen. It's a powerful piece of software that allows Nimbus to generate Xcode docsets and documentation that is accessible from the web.

Out of the box, Doxygen does not provide as much support for generating Apple-esque documentation as would be desired, so Jeff has been hacking on Nimbus to get it to generate documentation that resembles Apple's docs.

You can download the custom build here: https://github.com/downloads/jverkoey/nimbus/Nimbus%20Doxygen.dmg.zip

And the source is accessible here: https://github.com/nimbusios/Doxygen

Generating the Documentation

After you've installed Doxygen on your system, open Doxywizard.

Open the Doxyfile found in Nimbus' docs directory. Run Doxygen and the documentation will be output in docs/output/html.

Generating the Xcode Docset

To generate the Xcode Docset, open Doxyfile-docset and run Doxygen. You will then need to open Terminal to docs/output-docset/html and run make install. This will build the docset and install it locally. In order to get Xcode to read the new docset you will have to restart Xcode.