Contributing a component to the Curated store

Ubuntu Component Store is intended to be a community project where app developers are encouraged to contribute any component that they think would be useful to other developers. To contribute a component to UCS, we recommend first joining the team by applying here. This would then make it possible for you to maintain your component by pushing bug fixes and improvements as and when you choose.

By moderating the members of the team and components in UCS, we can promise a well tested component with a stable API. We recognize that this can impede the rate at which new components can be added to UCS, but we feel that this is an acceptable drawback to ensure good quality components to our userbase.

Let’s go through the steps required to upload a new component to the store.

Getting Started

You can technically contribute new components to the store without being a member of the team by requesting someone from the team to maintain your component. However we highly recommend that you join the team since that would allow you to push bug fixes and improvements to your component quickly. You can apply to become a member by applying here. The approval should be done within a day or two.

UCS is hosted on launchpad and requires bazaar (bzr) to grab or push the code. As such you would need to have an account on launchpad and be familiar with bzr. You can grab the code by,

bzr branch lp:component-store

UCS by itself is an ordinary QML project. You should be able to open it using qtcreator like any other project. Run the UCS Gallery app by either pressing the green button in qtcreator or via the command line as shown below,

qmlscene main.qml

This should open the UCS Gallery app as shown below. It provides a visual overview of all the components in the store.

Note

At the time of writing this documentation, you would need a 14.10 desktop to run the component store gallery. You can run the gallery app on the phone or emulator using a 14.04 desktop, however the gallery app doesn’t converge well on the phone yet. This should be fixed soon.

Adding a new component to the store

Adding a new component to the store involves 3 main steps which are,

1. Adding a new component to the ComponentStore folder
2. Updating the gallery app to showcase your new component
3. Updating the documentation

Adding a new component to the ComponentStore Folder

The components are stored in their own folders in the ComponentStore folder. Let’s assume for illustration purposes, we are trying to add a new component MyNewComponent to UCS. Let’s grab UCS first and then add the new component.

bzr branch lp:component-store MyNewComponentBranch

Let create a new folder for our component in the ComponentStore folder,

cd MyNewComponentBranch/ComponentStore
mkdir MyNewComponent && bzr add MyNewComponent
cd MyNewComponent

Inside your MyNewComponent folder, add your generic component files. Everything that is required to use your component must be included in this folder. Let’s now add these files to the source control bzr and commit them.

bzr add *
bzr commit -m "Added my new component"

Updating the gallery app

Now that we have our component ready and added, let’s update the gallery app to show that. Create a new file in the GallerySRC folder called MyNewComponentWidget.qml. This file is rather easy to fill out. Just copy the code from the other widget template files. It basically involves filling in information like the author, license, contact and a description of your component which is rather simple. Once completed, add MyNewComponentWidget.qml to the version control.

cd GallerySRC
bzr add MyNewComponentWidget.qml
bzr commit -m "Showcase new component in the gallery"

Next, open WidgetsModel.qml and add your component to the list. That’s it! Run the gallery app and see if your component shows up as expected.

Updating the documentation

This is one of the most important steps and benefits of adding your component to UCS. By providing a well written and clear documentation you make it easier for other app developers to use your component in their app. All the documentation is hosted in the docs folder. Create a new documentation file in the _components folder and fill in the necessary documentation. Use the existing documentation files to help you with setting it up.

Once done, add your component to the list in index.rst. Now let’s test if the documentation looks good. To build the documentation, you need sphinx and pip packages to be installed. Let’s install that for the first time.

sudo apt-get install pip
sudo pip install sphinx sphinx-autobuild

Building your documentation is now really simple. Once the build process is complete, open _build/index.html in your browser to see your documentation.

make html

Once again, let’s add this to the version control.

cd docs/_components
bzr add MyNewComponent.rst
bzr commit -m "Added documentation for the new component"

That was it! Your component is ready. Let’s push this online to UCS.

bzr push lp:~launchpad-id/component-store/MyNewComponentBranch

From there on, it is just a matter of reviewing the code (for new components, we try to ensure everything is in order) and then merging to trunk.