← Back to branch summary

~nik90/component-store/fix-debian-packaging

« back to all changes in this revision

Viewing changes to docs/contribute.rst

  • Committer: Stuart Langridge
  • Date: 2015-01-04 12:05:08 UTC
  • Revision ID: sil-launchpad@kryogenix.org-20150104120508-enrpvh0njrdl6vr9
Update documentation to describe the curated and community stores, and how to contribute to the community store. Also tweak a bug in ucs for searching curated components.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/contribute.rst
1
1
Contributing to UCS
2
2
===================
3
3
 
4
 
Ubuntu Component Store is intended to be a community project where app developers are
5
 
encouraged to contribute any component that they think would be useful to other developers.
6
 
To contribute a component to UCS, we recommend first joining the team by applying `here`_.
7
 
This would then make it possible for you to maintain your component by pushing bug fixes and
8
 
improvements as and when you choose.
9
 
 
10
 
By moderating the members of the team and components in UCS, we can promise a well tested
11
 
component with a stable API. We recognize that this can impede the rate at which new components
12
 
can be added to UCS, but we feel that this is an acceptable drawback to ensure good quality
13
 
components to our userbase.
14
 
 
15
 
Let's go through the steps required to upload a new component to the store.
16
 
 
17
 
Getting Started
18
 
---------------
19
 
 
20
 
You can technically contribute new components to the store without being a member of the team by
21
 
requesting someone from the team to maintain your component. However we highly recommend that you
22
 
join the team since that would allow you to push bug fixes and improvements to your component
23
 
quickly. You can apply to become a member by applying `here`_. The approval should be done within a
24
 
day or two.
25
 
 
26
 
UCS is hosted on launchpad and requires bazaar (bzr) to grab or push the code. As such you would
27
 
need to have an account on launchpad and be familiar with bzr. You can grab the code by, ::
28
 
 
29
 
    bzr branch lp:component-store
30
 
    
31
 
UCS by itself is an ordinary QML project. You should be able to open it using qtcreator like any other
32
 
project. Run the UCS Gallery app by either pressing the green button in qtcreator or via the command line
33
 
as shown below, ::
34
 
 
35
 
    qmlscene main.qml
36
 
 
37
 
This should open the UCS Gallery app as shown below. It provides a visual overview of all the components
38
 
in the store.
39
 
 
40
 
.. image:: _images/gallery.png
41
 
   :align: center
42
 
   :scale: 90 % 
43
 
   
44
 
.. 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.
45
 
   
46
 
Adding a new component to the store
47
 
-----------------------------------
48
 
 
49
 
Adding a new component to the store involves 3 main steps which are,
50
 
 
51
 
1. Adding a new component to the ComponentStore folder
52
 
2. Updating the gallery app to showcase your new component
53
 
3. Updating the documentation
54
 
 
55
 
Adding a new component to the ComponentStore Folder
56
 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
57
 
 
58
 
The components are stored in their own folders in the ComponentStore folder. Let's assume for illustration purposes, 
59
 
we are trying to add a new component *MyNewComponent* to UCS. Let's grab UCS first and then add the new component. ::
60
 
 
61
 
    bzr branch lp:component-store MyNewComponentBranch
62
 
 
63
 
Let create a new folder for our component in the ComponentStore folder, ::
64
 
 
65
 
    cd MyNewComponentBranch/ComponentStore
66
 
    mkdir MyNewComponent && bzr add MyNewComponent
67
 
    cd MyNewComponent
68
 
    
69
 
Inside your *MyNewComponent* folder, add your generic component files. Everything that is required to use your component
70
 
must be included in this folder. Let's now add these files to the source control bzr and commit them. ::
71
 
 
72
 
    bzr add *
73
 
    bzr commit -m "Added my new component"
74
 
 
75
 
Updating the gallery app
76
 
^^^^^^^^^^^^^^^^^^^^^^^^
77
 
 
78
 
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
79
 
folder called MyNewComponentWidget.qml. This file is rather easy to fill out. Just copy the code from the other widget template
80
 
files. It basically involves filling in information like the author, license, contact and a description of your component which
81
 
is rather simple. Once completed, add MyNewComponentWidget.qml to the version control. ::
82
 
 
83
 
    cd GallerySRC
84
 
    bzr add MyNewComponentWidget.qml
85
 
    bzr commit -m "Showcase new component in the gallery"
86
 
 
87
 
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
88
 
as expected.
89
 
 
90
 
Updating the documentation
91
 
^^^^^^^^^^^^^^^^^^^^^^^^^^
92
 
 
93
 
This is one of the most important steps and benefits of adding your component to UCS. By providing a well written and clear documentation
94
 
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
95
 
a new documentation file in the _components folder and fill in the necessary documentation. Use the existing documentation files to help you
96
 
with setting it up. 
97
 
 
98
 
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
99
 
need sphinx and pip packages to be installed. Let's install that for the first time. ::
100
 
 
101
 
    sudo apt-get install pip
102
 
    sudo pip install sphinx sphinx-autobuild
103
 
    
104
 
Building your documentation is now really simple. Once the build process is complete, open _build/index.html in your browser to see your documentation. ::
105
 
 
106
 
    make html
107
 
 
108
 
Once again, let's add this to the version control. ::
109
 
 
110
 
    cd docs/_components
111
 
    bzr add MyNewComponent.rst
112
 
    bzr commit -m "Added documentation for the new component"
113
 
    
114
 
That was it! Your component is ready. Let's push this online to UCS. ::
115
 
 
116
 
    bzr push lp:~launchpad-id/component-store/MyNewComponentBranch
117
 
    
118
 
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.
119
 
 
120
 
.. _here: https://launchpad.net/~ubuntu-touch-community-dev
 
4
There are two sorts of components in the Ubuntu Component Store: *Curated* components and *Community* components. As a  developer, you can publish your component to either. Components in the Curated store have higher requirements to ensure that they are high-quality; anyone can publish to the Community store without approval.
 
5
 
 
6
Contributing a component
 
7
------------------------
 
8
 
 
9
.. toctree::
 
10
   :maxdepth: 1
 
11
 
 
12
   contribute-curated
 
13
   contribute-community