~registry/cambria/trunk

Why do we need these tools?
===========================

Project cambria is about wrapping the existing tools for Debian/Ubuntu
development to allow a more task-based workflow. Depending on the task the
developer is doing there may be several things that must be done, but they
must currently work each one out individually. We have documentation to help
with this, but it's much simpler if your tools can take care of it for you.

Project cambria aims to make Ubuntu development easier to get started with.
There are several ways that it will help. Providing a task-based workflow
where you are prompted for the information that is needed to complete the
task, and other things are done automatically, or defaults chosen helps as
it means you can concentrate on completing the task, rather than learning
about all the possible changes you could make and deciding which applies.

Project cambria aims to make Ubuntu development easier for everyone by
automating common tasks, and alleviating some of the tool tax that we pay.
It won't just be a beginner tool, but will provide tools and APIs that
experienced developers can use, or can build upon to build tools that suit
them.

Project cambria will help to take people from novice to experienced
developer by providing documentation that allows you to learn about the
issues related to your current task. This provides an easier way in to the
documentation than a large individual document (but it can still be read
that way if you like).

Project cambria will make Ubuntu development more pleasurable by focusing
on the user experience. It will aim to pull together disparate interfaces
in to a single pleasing one. Where it needs to defer to a different interface
it should provide the user with an explanation of what they will be seeing
to lessen the jarring effect.

That's all well and good, but what do you mean?
===============================================

See the mockups/ directory for some ideas about what could be done to
achieve this.

Great, how can I try it?
========================

There isn't a lot to try yet. The following projects are ongoing to
work towards this

  * cambria (this project) - http://launchpad.net/cambria
  * ubuild (a library for building packages) - https://launchpad.net/ubuild
  * gedit-ubudev (a GEdit plugin for doing Ubuntu development)
     - https://edge.launchpad.net/gedit-ubudev


First create a new directory to contain all of the branches related
to cambria.

  mkdir ~/project-cambria
  cd ~/project-cambria

The first thing to get is ubuild:

  bzr branch lp:ubuild
  cd ubuild
  # This installs the D-Bus configuration files that are neccesary
  # for it to work.
  ./install-dbus
  cd ..

Then you can get cambria:

  bzr branch lp:cambria

Then the gedit plugin:

  bzr branch lp:gedit-ubudev
  cd gedit-ubudev
  ./install-gedit-plugin
  cd ..

Now if you run

  ./gedit-ubudev/run-gedit

you should get gedit with the Ubuntu Packaging plugin available,
but before you can use it you have to enable it. To do this
go to Edit->Preferences, to the Plugins tab, and scroll down to
find "Ubuntu Packaging" and check the box next to it. If it is
greyed-out then there was a problem loading the plugin, in which
case look at the console output and file a bug with the messages.


Sounds like a great idea, but it clearly needs work, how do I help?
===================================================================

You are right, there is a lot of work needed, from a lot of people. In fact,
there's probably a job for anyone. Here's an incomplete list of what we
need, feel free to help in other ways or ask for ideas.

UI design
---------

We need good UI design, especially for the GUI tools. It needs to take
in to account the needs of developers, either for Ubutnu, or for e.g. PPAs
and combine them in a user interface that is a pleasure to use and helps
more than it gets in the way. This will often be tricky, but it doesn't
mean we shouldn't try.

If you have some ideas then please draw some mockups of them and we can
discuss them. They will need to be extended from mockups in to
specifications of how the elements should work after that.

UI implementors
---------------

Once we have these fantastic mockups then they need to be converted to code
so that they can be used. This requires UI implementors, either writing code
or using a GUI tool such as glade.

At this stage the UIs don't have to do anything, we can worry about that part
later, once the next group have something to use.

API/library coders
------------------

We need libraries for the tasks we want to allow people to perform. These
libraries need to have APIs that are flexible enough to allow different
implementations (command line, gtk, qt, etc.), but are as pleasurable
to use as the tools we wish to create.

That's the goal though, the first aim would be to have working code.

There's many many things we need libraries writing for, and we don't
need UI mockups to get started with the coding, so start hacking on the
existing libraries, or ask about other things that need coding.

Documenters
-----------

Documentation is going to be incredibly important to this project, and
so documenters will be too. We need to document both the tools themselves
and Ubuntu development together so that the developer can seamlessly learn
that something needs to be done and how to go about doing it.

This is a very large topic, but we can get a lot of benefit from having
something small to start with. Feel free to ask about things that neeed
documentation.

Translations
------------

To make this tool pleasurable for the widest audience we should ensure that
it is well-localised. We should make sure that code we write is localised,
and also encourage other projects to do the same.

Unfortunately we are lagging on this aspect, and so the first step will be
to add in the basic infrastructure to allow localisation.

Packagers
---------

We need to package up all the results of the above, otherwise no-one
will be able to easily use them.

In addition though, we need packagers to be the users of the tools we
create, so that we know how well they fit the purpose. This means
that packagers are our users and testers too. You don't have to be
an Ubuntu developer to do this though. Whether you are, you are
working towards it, or just have some things you want to put in to
a PPA you can help.

More
----

There is loads more to be done. There should be more sections added
here, but we will never be able to list everything. If you have an
idea for what could be done then talk to us and we will help you
work out the best way to achieve it.


How do I actually go about submitting my work?
==============================================

UI design
---------

When you have an idea or a mockup that you would like to discuss
go to

  https://bugs.launchpad.net/cambria/+filebug

and fill in a summary of your idea. It will suggest some possible
matches, but it's always fine to submit a new bug that we can
mark as a duplicate later if necessary. Then on the next page explain
it in more detail, don't worry about trying to explain everything,
just include all you can at that point. Once you are done click
"Submit Bug Report."

If you have mockups or other files that you want other people to see
you can attach them to the bug report when you have created it.

Once you have submitted the bug we can discuss the idea and take
it from there.

UI Implementation
-----------------

If you want to work external to the existing code then you can
do the same as for UI design and attach the files to a bug report,
otherwise you can submit the changes in a Bazaar branch if you
are comfortable with that. See the API/library code section for
information on doing that.

API/Library code
----------------

Earlier it was explained how to get the code and run it, so that
is most of the way to being able to work on it.

One tricky part is working out which component you should be
changing to work on something. Feel free to ask for guidance.

As you will no doubt see, getting and running the code isn't
as slick as it could be, so contributions there would be very
valuable at this stage.

Documentation
-------------

We don't have a documentation structure at all yet, so the first
step will be to define that. If you want to tackle this then file
a bug so that we can discuss what the best method is.

Translations
------------

As said above, we don't have any infrastructure. If you want to take
on this job then you can file a bug to get some guidance, or you
can dive straight in to code changes if you know how.

Packagers
---------

For packaging the code itself we want packaging branches made for
each project. If you are interested in this but need some help
file a bug where we can dicsuss it.

If you want to use the tools then see above for how to go about
doing that. As you are doing so please file bug reports and
feature requests (though bear in mind that the project is in
its infancy, and so there will be many many known issues.) A
good way to contribute at this stage would be explaining what
task you want to accomplish and what steps are needed. This can
be done in a bug report.

More
----

If you have an idea and want to discuss it then file a bug report.
If you want a suggestion of something to work on then file a bug,
send an email, or grab someone on IRC. You can also look at the open
bug reports at

  https://bugs.launchpad.net/cambria/+bugs

to see if there is anything you would like to work on.