|
1
|
|
-# BuildStream policies
|
|
|
1
|
+## Content Structure Full Proposal
|
|
2
|
2
|
|
|
3
|
|
-## Hacking on BuildStream
|
|
|
3
|
+In the same way that a software product requires an architecture, the contents of a product do too, for similar reasons, being scalability and maintainability two of the important ones.
|
|
4
|
4
|
|
|
5
|
|
-Every policy related with hacking or developing BuildStream is described in the technical documentation: <https://buildstream.gitlab.io/buildstream/HACKING.html>
|
|
|
5
|
+Based on previous experiences managing Open Source projects (products) I would like you to evaluate the following proposal which I've called "Content Structure". As usual, I am open to suggestions when it comes to naming.
|
|
6
|
6
|
|
|
7
|
|
-## BuildStream on Gitlab: policies
|
|
|
7
|
+There are three diagrams[1][2][3] that support the current proposal. Please take a look at them while reading this document. One final document includes all of the three[4].
|
|
8
|
8
|
|
|
9
|
|
-Description of the main elements on Gitlab used at BuildStream.
|
|
10
|
9
|
|
|
11
|
|
-### Milestones
|
|
|
10
|
+### Content Units
|
|
12
|
11
|
|
|
13
|
|
-Milestone on Gitlab matches relevant events that are related with time frames like release cycles and events. The only current global milestones across the entire BuildStream Group are release cycles.
|
|
|
12
|
+The structure is based on related "Content Units", a name used to avoid the association of any of those units with a specific tool, the concept of a "page" or a "file".
|
|
14
|
13
|
|
|
15
|
|
-General description of how milestones work on Gitlab: <https://docs.gitlab.com/ee/user/project/milestones/>
|
|
|
14
|
+For example:
|
|
16
|
15
|
|
|
17
|
|
-Global milestones on Gitlab: <https://gitlab.com/groups/BuildStream/-/milestones>
|
|
|
16
|
+* Wikis allow to embed the content of a page in another page.
|
|
|
17
|
+* Two content units can be published initially in a single web page and, when they expand, separated into two.
|
|
18
|
18
|
|
|
19
|
|
-### Labels
|
|
20
|
19
|
|
|
21
|
|
-Labels allow us to structure, filter and visualise some of the Gitlab elements in different ways. Some of those labels apply to the entire BuildStream group and some only apply to specific repositories (projects).
|
|
|
20
|
+I will refer to pages or files only in specific cases.
|
|
22
|
21
|
|
|
23
|
|
-Check the description of labels on Gitlab: <https://docs.gitlab.com/ee/user/project/labels.html>
|
|
24
|
22
|
|
|
25
|
|
-Check the global scale labels: <https://gitlab.com/groups/BuildStream/-/labels>
|
|
|
23
|
+### Target audience
|
|
26
|
24
|
|
|
27
|
|
-The global ones are:
|
|
|
25
|
+Based on the BuildStream target audience, I propose, for simplicity to consider the following target audience when it comes to content design:
|
|
28
|
26
|
|
|
29
|
|
-* Status scale:
|
|
30
|
|
- * Backlog: default state on Gitlab so no label needed.
|
|
31
|
|
- * Todo: processed elements that should be done in the future.
|
|
32
|
|
- * Doing: WIP
|
|
33
|
|
- * Review: items that are under review once the developer or contributor has finished it.
|
|
34
|
|
- * Closed: items that has been processed and canceled, finished or no longer apply. Default state on Gitlab so no label needed.
|
|
35
|
|
-* Severity scale (these labels are prioritized):
|
|
36
|
|
- * No label: unprocessed item, no or low priority.
|
|
37
|
|
- * Important: default severity for processed items that should be executed/considered.
|
|
38
|
|
- * Urgent: to pay attention in the immediate future when possible.
|
|
39
|
|
- * Critical: topics that require attention immediately when possible.
|
|
40
|
|
-* Impact scale: this scale is restricted to the buildstream project for now.
|
|
41
|
|
- * high_impact: the crash/feature/task takes place frequently or is a recurrent one and has a significant impact on users everyday or key work.
|
|
42
|
|
- * No label: the crash/feature/task is infrequent or hard to reproduce and the impact on the users is low or hard to determine.
|
|
43
|
|
-* Topic labels: each repository has its own labels that allow to structure tickets per topic.
|
|
|
27
|
+* Those unaware of the existence of BuildStream (99%)
|
|
|
28
|
+* Those aware of the existence of BuildStream (1%)
|
|
|
29
|
+ * BuildStream users (0.1%)
|
|
|
30
|
+ * BuildStream contributors (0.001%)
|
|
44
|
31
|
|
|
45
|
|
-Check the buildstream project specific topic labels: <https://gitlab.com/BuildStream/buildstream/labels>
|
|
46
|
32
|
|
|
47
|
|
-Check the nosoftware repos topic labels
|
|
|
33
|
+In general, when I refer to users, I will also be referring to contributors. As the project, so the content, matures, it would be ideal to segment some of the above target audiences.
|
|
48
|
34
|
|
|
49
|
|
-* communication project labels: <https://gitlab.com/BuildStream/nosoftware/communication/labels>
|
|
50
|
|
-* alignment project labels: <https://gitlab.com/BuildStream/nosoftware/alignment/labels>
|
|
|
35
|
+Occasionally, the proposal or/and content itself might refer to the following subgroups:
|
|
51
|
36
|
|
|
52
|
|
-In order to propose new labels or a change in the current ones, please send a mail to the mailing list or add a ticket in the alignment repo: <https://gitlab.com/BuildStream/nosoftware/alignment/issues>
|
|
|
37
|
+* Users
|
|
|
38
|
+ * Integrators: those who use BuildStream as part of the delivery process (integration stage).
|
|
|
39
|
+ * Developers: those who use BuildStream as part of their development process.
|
|
|
40
|
+* Contributors
|
|
|
41
|
+ * Core contributors: those who contribute on regular basis, normally to specific/key areas.
|
|
|
42
|
+ * Occasional, sporadic, opportunistic contributors: the rest of the contributors.
|
|
53
|
43
|
|
|
54
|
|
-### Issue Boards
|
|
55
|
44
|
|
|
56
|
|
-Boards allow anybody interested in BuildStream to visualise and manage (workflow) issues in a simple way. BuildStream has boards at global level (group), subgroup level (nosoftware) and project level.
|
|
|
45
|
+This might provide a hint on further target audience segmentation we can define in the coming future.
|
|
57
|
46
|
|
|
58
|
|
-* Check the description of labels on Gitlab: <https://about.gitlab.com/features/issueboard/>
|
|
59
|
|
-* Check the global boards: <https://gitlab.com/groups/BuildStream/-/boards/580444?milestone_title=BuildStream_v1.1>&=
|
|
60
|
|
-* Check the buildstream repo specific boards: <https://gitlab.com/BuildStream/buildstream/boards/580451?milestone_title=BuildStream_v1.1>&=
|
|
61
|
|
-* There is a menu in the above pages to select every available board.
|
|
62
|
47
|
|
|
63
|
|
-There are three main groups of boards:
|
|
|
48
|
+### Tools
|
|
64
|
49
|
|
|
65
|
|
-* Status boards: allow anybody to visualize Work in Progress (WIP) and move tickets from one status to another one so there is no need to manually change the labels, including when a ticket is closed.
|
|
66
|
|
-* Severity boards: allow anybody to visualize how relevant the tickets are for developers, based on a variety of criteria that ends up on a notion of priority. It also is useful to move the tickets from one severity state to another one so there is no need to manually change the labels, including when a ticket is closed.
|
|
67
|
|
-* Other boards: there are other kind of boards for specific use cases.
|
|
|
50
|
+Initially we will work with what we have:
|
|
68
|
51
|
|
|
69
|
|
-### Templates
|
|
|
52
|
+* Gitlab:
|
|
|
53
|
+ * The current guide.
|
|
|
54
|
+ * Key files in repos (specially buildstream.
|
|
|
55
|
+* The GNOME wiki
|
|
70
|
56
|
|
|
71
|
|
-The usage of issues and merge requests templates allow community members to understand which information is required for developers and contributors to fully understand and process the bug/task/request adequately. Templates are assigned per project/repo and need to be selected when creating an issue or merge request.
|
|
72
|
57
|
|
|
|
58
|
+The structure is designed to be as "tool agnostic" as possible.
|
|
73
|
59
|
|
|
74
|
|
-Check the information about templates from Gitlab: <https://docs.gitlab.com/ee/user/project/description_templates.html>
|
|
|
60
|
+We will focus initially on git based content, using gitlab capabilities for it. On the wiki, we will focus on having a good "front page" and improving a little the current content. With this approach, we expect to get ready for when a web comes reducing the effort that keeping the information on the wiki and git on sync.
|
|
75
|
61
|
|
|
76
|
|
-Check the templates used at BuildStream:
|
|
77
|
|
-* buildstream repo/project templates:
|
|
78
|
|
- * Default template:
|
|
79
|
|
- * Bug template:
|
|
80
|
|
- * Merge request template:
|
|
81
|
|
-* alignment/communication repos templates:
|
|
82
|
|
- * task template: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/.gitlab/issue_templates/task.md
|
|
83
|
|
- * bug template: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/.gitlab/issue_templates/bug.md
|
|
84
|
|
- * Merge request template: https://gitlab.com/BuildStream/buildstream/blob/master/.gitlab/merge_request_templates/bst_merge_request.md
|
|
|
62
|
+One risk we need to strongly consider is related with the links strategy. There are several ways to approach this issue and it will be a matter of policy. Breaking links might through to the garbage not just internal references, so out pre-defined critical paths, but also external references to our content.
|
|
85
|
63
|
|
|
86
|
|
-## Technical/engineering tasks: best practices.
|
|
87
|
64
|
|
|
88
|
|
-These are the best practices that are applied to Gitlab at BuildStream in relation with bugs and tasks. Please read them carefully and try to apply them.
|
|
89
|
|
-
|
|
90
|
|
-### Open/create a technical issue
|
|
|
65
|
+### Timeline
|
|
91
|
66
|
|
|
92
|
|
-In order to open a new task the best place is the green button at this page: <https://gitlab.com/BuildStream/buildstream/issues>. Please follow these considerations:
|
|
93
|
|
-* Use the default template.
|
|
94
|
|
-* Fill out the information required.
|
|
95
|
|
- * Select the milestone/version affected or related with the task.
|
|
96
|
|
- * If the ticket is related with the current milestone/version and older, please leave the default option.
|
|
97
|
|
-* Save the ticket.
|
|
98
|
|
-* Apply further metadata if you are sure about which labels to use.
|
|
99
|
|
- * Leave the Assignee blank unless you know who is the person responsible for that issue.
|
|
100
|
|
- * Consider applying topic labels if are familiar with them.
|
|
101
|
|
- * If the issue is just a breakdown of another task, please consider applying the same topic labels.
|
|
102
|
|
-* Further considerations:
|
|
103
|
|
- * If you want to notify somebody about the ticket, please add his/her name as first comment. Try to avoid naming people for notification reasons in the ticket description.
|
|
104
|
|
- * It is extremely useful that you use the Related Topics field adding:
|
|
105
|
|
- * #"ticket id" if the ticket you just created is related with another ticket from the same repo.
|
|
106
|
|
- * Relative link if the ticket you just created is related with a ticket from the BuildStream group or a different group within gitlab.com.
|
|
107
|
|
- * A full URL if the ticket is related with a gitlab ticket under a different domain.
|
|
108
|
|
- * The MR associated with the ticket. Please do not forget this.
|
|
109
|
|
- * If your issue remains unprocessed after a few days/weeks, please ask through the project mailing list about it. It should be the exception but it might have been overlooked or remain unnoticed.
|
|
|
67
|
+Ideally, we will have those contents directly related with the release ready for the Release Date (RD) and the rest would be done little by little, having ELCE 2018 as a key milestone.
|
|
|
68
|
+
|
|
|
69
|
+
|
|
|
70
|
+### Content management
|
|
|
71
|
+
|
|
|
72
|
+Since this is an Open Source project, the best way to receive meaningful contributions in this area is to define the structure, create minimal contents based on the structure for at least the essential units and provide the community some guidelines on how to contribute. This will be the approach I propose to follow vs the approach in which contents are only published when finished.
|
|
|
73
|
+
|
|
|
74
|
+As you already know by now, if we want good contents we will need to be as serious about them as we are about code. We have a good example on the current guide. We will create a web repo in nosoftware subgroup including a bug tracked about it. A proposal on how to relate this ticketing system with the existing ones and the current Documentation label will be sent to the list.
|
|
|
75
|
+
|
|
|
76
|
+A key part of the maintainability story when it comes to content are labels/tags and URLs. We will need to pay special attention to them and create very specific policies on how to create and update them.
|
|
|
77
|
+
|
|
|
78
|
+Except the front page of the wiki, we will focus initially on the release related content. Before ELCE 2018, we will put additional effort on the wiki.
|
|
|
79
|
+
|
|
|
80
|
+
|
|
|
81
|
+### Criteria followed to structure the content units
|
|
|
82
|
+
|
|
|
83
|
+Assuming the Open Source nature of the project and the fact that we are developing an integration tool for a pre-defined target audience, the following criteria has been followed to structure the proposed content units:
|
|
|
84
|
+
|
|
|
85
|
+
|
|
|
86
|
+#### Expected content change rate
|
|
|
87
|
+
|
|
|
88
|
+
|
|
|
89
|
+Some content units will have a higher change rate than others. Separate them in different content units is essential to reduce in the future the maintenance effort. It also helps to decide which tool could appropriate for each unit too.
|
|
|
90
|
+
|
|
|
91
|
+For simplicity, I have considered the following groups:
|
|
|
92
|
+
|
|
|
93
|
+* (almost) Static: content that is not expected to change frequently, i.e. project principles or Manifest.
|
|
|
94
|
+* Dynamic: content that is expected to change frequently, grow overtime or have a limited life expectancy.
|
|
|
95
|
+* Replaceable: due to the nature of our activity, there is a specific subset of content that will be replaced by new content when a specific event occurs, mostly releases. Do no mistake replaceable with erasable. In theory, these contents will not be erased but new content will play its role.
|
|
|
96
|
+* Erasable: temporary pages that will die for exceptional reasons, like the usage of a new tool.
|
|
|
97
|
+
|
|
|
98
|
+
|
|
|
99
|
+#### Front page vs project and landing pages
|
|
|
100
|
+
|
|
|
101
|
+
|
|
|
102
|
+There are two main content units we will used as "root units" in terms of the proposed content structure:
|
|
|
103
|
+
|
|
|
104
|
+* Project page.
|
|
|
105
|
+* Landing page.
|
|
|
106
|
+
|
|
|
107
|
+
|
|
|
108
|
+I refer to them as pages, instead of units, because they are single pages and also because is a very common terminology.
|
|
|
109
|
+
|
|
|
110
|
+Please be aware that these pages will not be designed as the BuildStream project front page (also common terminology). Until we have a web (hopefully for ELCE 2018) we will have a simple front page on the wiki, as today, which will be designed to die (erasable).
|
|
|
111
|
+
|
|
|
112
|
+The project page and the landing page might be moved to the future web, depending on design, effort and maintenance related decisions. Based on it, the current wiki front page (project wiki page in GNOME terminology) might change.
|
|
|
113
|
+
|
|
|
114
|
+
|
|
|
115
|
+#### Outcomes as the most influential event
|
|
|
116
|
+
|
|
|
117
|
+
|
|
|
118
|
+Assuming the most common journey to become a maintainer (not the only one):
|
|
|
119
|
+
|
|
|
120
|
+Humanity -> User -> Power user -> Occasional Contributor -> Core contributor -> Maintainer
|
|
|
121
|
+
|
|
|
122
|
+at this point of maturity of the project, releases allow us to maximize the impact of our efforts to gain users while, at the same time, it help us internally to synchronize the efforts of contributors and power users with different goals and expectations.
|
|
|
123
|
+
|
|
|
124
|
+As the project matures and the number of users grow we might evolve our focus towards gaining contributors, for instance. The structure, with the support of the critical path definitions, should evolve too.
|
|
|
125
|
+
|
|
|
126
|
+In my experience, using the concept of releases as criteria for defining the content structure of projects that:
|
|
|
127
|
+
|
|
|
128
|
+* Need the kind of attention that leads them to find users with technical profile.
|
|
|
129
|
+* Does not have a meaningful number of experienced technical product content creators.
|
|
|
130
|
+* Cannot or do not want to heavily invest in promotion/marketing activities compared to development ones.
|
|
|
131
|
+
|
|
|
132
|
+
|
|
|
133
|
+.... work well.
|
|
|
134
|
+
|
|
|
135
|
+
|
|
|
136
|
+#### Use cases and sister projects
|
|
|
137
|
+
|
|
|
138
|
+
|
|
|
139
|
+BuildGrid has been considered as a "sister project". Initially, it can rely of the current structure to minimize the effort required from their side.
|
|
|
140
|
+
|
|
|
141
|
+Freedesktop-SDK can be considered explicitly in several units, like in Pr.1 D.1, D.4 and D.5 There is plenty of room for collaboration.
|
|
|
142
|
+
|
|
|
143
|
+Additional use cases can also be considered in several units. I hope you agree with me that the proposed structure leaves enough room to accommodate them. Otherwise, please let me know.
|
|
|
144
|
+
|
|
|
145
|
+### Topic
|
|
|
146
|
+
|
|
|
147
|
+The content has been structured in 6 different groups based on topic. Some units might be part of several groups so please point out when you feel the grouping might be too controversial. this grouping helps to structure the proposal but it has no direct relation with how the final "pages" are linked in most cases. Please check the BuildStream_Content_Structure_diagram.pdf image[1].
|
|
|
148
|
+
|
|
|
149
|
+The topics are:
|
|
|
150
|
+
|
|
|
151
|
+* Community (Pj - project): content related with the community project, not necessarily with the outcome of the project.
|
|
|
152
|
+* Management (M): content related with the management of the roadmap, development and delivery of the outcomes of the project.
|
|
|
153
|
+* Promotion: content related with the promotion of the project in general, and the activities involved in producing the outcomes in particular.
|
|
|
154
|
+* Code and metadata: content units directly related with the code and metadata.
|
|
|
155
|
+* BuildStream description: content units related with the description of the outcomes and some specific content that helps in consumption and community support activities.
|
|
|
156
|
+* Outcomes: contents directly related with the outcomes that are "released" and/or consumed by users.
|
|
|
157
|
+* Landing page and project page: root pages of the key/essential content with a very specific purpose.
|
|
|
158
|
+
|
|
|
159
|
+
|
|
|
160
|
+### Content structure description
|
|
|
161
|
+
|
|
|
162
|
+
|
|
|
163
|
+Please check the diagram called BuildStream Content Structure, which is the first page of the attached .pdf file. You can also find the image in the gitlab[1]
|
|
|
164
|
+
|
|
|
165
|
+
|
|
|
166
|
+#### 0. BuildStream tool landing page
|
|
|
167
|
+
|
|
|
168
|
+
|
|
|
169
|
+This would be the starting point for those looking for a general definition of what BuildStream is and what is for. It is meant to be a static page.
|
|
|
170
|
+
|
|
|
171
|
+
|
|
|
172
|
+#### 1. BuildStream project page
|
|
|
173
|
+
|
|
|
174
|
+
|
|
|
175
|
+This would be the starting/root point for those contents related with the BuildStream Open Source project.
|
|
|
176
|
+
|
|
|
177
|
+
|
|
|
178
|
+#### C. BuildStream Code
|
|
|
179
|
+
|
|
|
180
|
+
|
|
|
181
|
+There is a well documented by now change in behavior when it comes to content consumption related with Open Source projects that favors for certain profiles specific repo files over content in other platforms, specially when the information is tightly related with the code.
|
|
|
182
|
+
|
|
|
183
|
+For complex and bigger project this trend represents a challenge since involves content maintenance related risks (inconsistency, duplication, outdated info...), specially when other content platforms are not git based, like in our case, where the GNOME wiki pages are editable.
|
|
|
184
|
+
|
|
|
185
|
+In terms of design, we will need to consider the following, to mitigate such risks:
|
|
|
186
|
+
|
|
|
187
|
+* README files will be nothing but a summary of what is present in other pages. Links to those pages will be included in the README file and will need to be maintained.
|
|
|
188
|
+* BuildStream will have the README file of the master branch as the entry point for contributors, instead of Master (outcome) unit initially. As the tool grows and becomes more mature, this decision might change.
|
|
|
189
|
+* The following relations need to be consider in order to avoid some of the mentioned risks:
|
|
|
190
|
+ * C.2 README.rst - R.2 Master, 0. Landing Page, R.3 Feature Page and R.4 Deployment Howto units.
|
|
|
191
|
+ * C.3 LICENSE file - Pj.2 Governance+license+sponsors content units.
|
|
|
192
|
+ * C.4 News/Release notes file - R.3 Feature page and D. BuildStream In Detail content units.
|
|
|
193
|
+ * C.5 Maintainers - Pj.5 Community support and Tools content unit.
|
|
|
194
|
+
|
|
|
195
|
+
|
|
|
196
|
+C.1 BuildStream download page
|
|
|
197
|
+
|
|
|
198
|
+The Download page is the central reference not just to download the outcomes delivered by the project, but also the associated metadata. It will also have structured and direct references to all the information required to have a smooth deployment/installation experience.
|
|
|
199
|
+
|
|
|
200
|
+The structure of this unit will consider:
|
|
|
201
|
+
|
|
|
202
|
+* Versioning.
|
|
|
203
|
+* Platforms where BuildStream is expected to be installed.
|
|
|
204
|
+* Deployment mechanisms/technologies.
|
|
|
205
|
+* Complementary plugins and tools required for the deployment/installation/usage of BuildStream.
|
|
|
206
|
+* Additional content units that any user needs to consider.
|
|
|
207
|
+* Critical path design to ensure that the journey through BuildStream contents takes place in the pre-established order. This consideration applies in fact to, at least, every unit that is part of the critical path of any considered target audience.
|
|
|
208
|
+
|
|
|
209
|
+
|
|
|
210
|
+C.2 Release branch and master README file
|
|
|
211
|
+
|
|
|
212
|
+Short, to the point, description of what is BuildStream for and how to consume it, together with links to further information, adding context to each one of them. That additional or complementary information could be (related with):
|
|
|
213
|
+
|
|
|
214
|
+* Documentation - D. BuildStream in detail unit
|
|
|
215
|
+* Community support (get help) - D.5 FAQ.
|
|
|
216
|
+* Contributing - Pj.3 How to contribute unit.
|
|
|
217
|
+* Licensing and copyrights - C.3 LICENSE and Pj.2 Governance+license+sponsors
|
|
|
218
|
+
|
|
|
219
|
+Relations: C.2 README.rst - R.2 Master, 0. Landing Page, R.3 Feature Page and R.4 Deployment Howto units.
|
|
|
220
|
+
|
|
|
221
|
+
|
|
|
222
|
+C.3 Release branch and master Copying/LICENSE file
|
|
|
223
|
+
|
|
|
224
|
+This unit should include:
|
|
|
225
|
+
|
|
|
226
|
+* Project license. Explicit description. Links.
|
|
|
227
|
+* Exceptions (if any) that are included in the repo. Explicit description. Links.
|
|
|
228
|
+
|
|
|
229
|
+Relations: C.3 LICENSE file - Pj.2 Governance+license+sponsors content units. A complementary proposal related with compliance will be sent.
|
|
|
230
|
+
|
|
|
231
|
+
|
|
|
232
|
+C.4 Release branch and Master (dev releases) NEWS/Release Notes.
|
|
|
233
|
+
|
|
|
234
|
+News related with each release (digested release notes). Further content can be considered in this unit or separate ones like:
|
|
|
235
|
+
|
|
|
236
|
+* Changelog
|
|
|
237
|
+* Raw release notes.
|
|
|
238
|
+
|
|
|
239
|
+Relations: C.4 News/Release notes file - R.3 Feature page and D. BuildStream In Detail content units.
|
|
|
240
|
+
|
|
|
241
|
+
|
|
|
242
|
+C.5 Release branch and master Maintainers file
|
|
|
243
|
+
|
|
|
244
|
+List of maintainers, responsibility and contact.
|
|
|
245
|
+
|
|
|
246
|
+Relations: C.5 Maintainers - Pj.5 Community support and Tools content unit.
|
|
|
247
|
+
|
|
|
248
|
+
|
|
|
249
|
+#### Pr. BuildStream Promotion
|
|
|
250
|
+
|
|
|
251
|
+
|
|
|
252
|
+Content units related with promoting BuildStream among the key targets including the promotion of the different releases, talks, finished features, etc. .
|
|
|
253
|
+
|
|
|
254
|
+Pr.1 BuildStream Out There
|
|
|
255
|
+
|
|
|
256
|
+This content unit collects the main references and contents about BuildStream that has been published by media or community members. It will also contain the data about the impact of the tool. Overtime, this unit becomes an important resource for a variety of decisions.
|
|
|
257
|
+
|
|
|
258
|
+Pr.2 Social media campaign
|
|
|
259
|
+
|
|
|
260
|
+Place to build social media campaigns, specially during the release of BuildStream. It also defines who and how the project is being promoted through social media.
|
|
|
261
|
+
|
|
|
262
|
+Pr.3 News / Announcements
|
|
|
263
|
+
|
|
|
264
|
+Announcements generated by the project, like release announcements. News to be consumed by community Members or supporters would be also a matter of this section/pages.
|
|
|
265
|
+
|
|
|
266
|
+Pr.4 Blog
|
|
|
267
|
+
|
|
|
268
|
+Project blog where contributors talk about what they have done/contributed.
|
|
|
269
|
+
|
|
|
270
|
+
|
|
|
271
|
+#### M. BuildStream Management
|
|
|
272
|
+
|
|
|
273
|
+
|
|
|
274
|
+Set of pages dealing with the management of the different aspects of the creation, release and maintenance of BuildStream toolset.
|
|
|
275
|
+
|
|
|
276
|
+
|
|
|
277
|
+M.1 BuildStream roadmap
|
|
|
278
|
+
|
|
|
279
|
+Roadmap description including the different release timelines.
|
|
|
280
|
+
|
|
|
281
|
+M.2 BuildStream release howto
|
|
|
282
|
+
|
|
|
283
|
+This content unit describes the management aspects of the release process.
|
|
|
284
|
+
|
|
|
285
|
+M.3 BuildStream development policies/guides
|
|
|
286
|
+
|
|
|
287
|
+Policies and guides that BuildStream developers should follow in order to get their code accepted, including unit tests and documentation.
|
|
|
288
|
+
|
|
|
289
|
+M.4 BuildStream delivery and operations policies/guides
|
|
|
290
|
+
|
|
|
291
|
+Set of guides and policies followed by those involved in delivery and operations tasks at BuildStream project, including information related with those managing the different services affecting the development, delivery and release.
|
|
|
292
|
+
|
|
|
293
|
+
|
|
|
294
|
+#### BuildStream in Detail
|
|
|
295
|
+
|
|
|
296
|
+
|
|
|
297
|
+This would be the content describing in detail the tool, including the features, components, dependencies and other elements. The ideal situation would be to have a page that provides an overall context of all the features, called BuildStream in Detail, and then links to more detailed information about each feature or component. It is important to provide a clear relation between problem statement/use case and feature.
|
|
|
298
|
+
|
|
|
299
|
+It is important to translate to the content the architecture of the tool when it comes to core vs complementary features if, like in our case, they are developed/managed slightly different, so the feature and associated content maintenance expectations are set correctly.
|
|
|
300
|
+
|
|
|
301
|
+It is important to link the feature descriptions to code, so the content is worth for a wide range of profiles, making the published content valuable in a wider range of situations.
|
|
|
302
|
+
|
|
|
303
|
+
|
|
|
304
|
+D.1 Integrate with BuildStream: examples
|
|
|
305
|
+
|
|
|
306
|
+Examples of how to use the tool. The content can be created and maintained by the project itself and or referenced from work done outside the project. AS in other cases, it should be a clear difference between what is expected to be maintained by the project participants and what is "external". This is relevant when requesting/providing support to users and when managing negative feedback on internet.
|
|
|
307
|
+
|
|
|
308
|
+
|
|
|
309
|
+D.2 BuildStream plug-ins and other complementary features
|
|
|
310
|
+
|
|
|
311
|
+The complementary features, like plugins, should be documented and it is this page the starting point. It is expected that some of this features will be developed outside the project so it is necessary to structure the content in a way that a user or contributor can identify what to expect from the project in terms of maintenance or/and community support.
|
|
|
312
|
+
|
|
|
313
|
+
|
|
|
314
|
+D.3 BuildStream core features description
|
|
|
315
|
+
|
|
|
316
|
+Detailed description of the core features shipped by BuildStream, including those who are new on each release. Ideally, this content will provide links to additional complementary documentation that would help readers to understand the use cases behind the features, the features description themselves and how to consume them.
|
|
|
317
|
+
|
|
|
318
|
+
|
|
|
319
|
+D.4 BuildStream glossary
|
|
|
320
|
+
|
|
|
321
|
+Each project uses specific terminology that requires explanation. In regulated or safety critical environments or in Open Ocean, this need becomes almost a requirement. The same principle applies to mature markets when using terminology as a differentiation element.
|
|
|
322
|
+
|
|
|
323
|
+BuildStream will have a glossary.
|
|
|
324
|
+
|
|
|
325
|
+
|
|
|
326
|
+D.5 BuildStream FAQ
|
|
|
327
|
+
|
|
|
328
|
+The FAQ is a relevant content element, often just appreciated by projects that has reached a mature state. BuildStream FAQ is proposed to become a key step in the critical path designed for two different target audiences at two different points in the "content journey", which means that this FAQ should be structured accordingly.
|
|
|
329
|
+
|
|
|
330
|
+
|
|
|
331
|
+#### BuildStream outcomes (portfolio)
|
|
|
332
|
+
|
|
|
333
|
+
|
|
|
334
|
+Contents related with the different "products" offered by the BuildStream project. Each outcome should have a separated content page. So far, we have three different outcomes:
|
|
|
335
|
+
|
|
|
336
|
+* Even releases: targeting users
|
|
|
337
|
+* Odd releases: targeting testers (users and contributors)
|
|
|
338
|
+* Master: targeting contributors
|
|
|
339
|
+
|
|
|
340
|
+
|
|
|
341
|
+R.1 BuildStream releases: portfolio charter
|
|
|
342
|
+
|
|
|
343
|
+This page will have links to all the BuildStream releases, highlighting the current one, the ones maintained or recommended for the different profiles, together with the links to the complementary information that might be related to releases, like roadmap, announcements, etc.
|
|
|
344
|
+
|
|
|
345
|
+
|
|
|
346
|
+R.2 Master
|
|
|
347
|
+
|
|
|
348
|
+Master as such is not released but in BuildStream portfolio, it is the default outcome for contributors. As such, this page would be the default to route first time contributors as well as occasional contributors that requires information about changes in policies and other topics that might affect Master.
|
|
|
349
|
+
|
|
|
350
|
+
|
|
|
351
|
+R.3 BuildStream releases feature page
|
|
|
352
|
+
|
|
|
353
|
+The feature page is the central page for each release, that contains the information about what is released, compared with previous releases. It also includes all the necessary links to have a wide view of how to evaluate consume and get community support for a specific release.
|
|
|
354
|
+
|
|
|
355
|
+
|
|
|
356
|
+R.4 BuildStream deployment howto
|
|
|
357
|
+
|
|
|
358
|
+Each release will have instructions on how to install/deploy BuildStream for the various platforms available. Part of this information would be created and maintained by the project itself and part will be available in other sites, external to the project. This page will ensure the information is available to those BuildStream users and contributors who intend to consume BuildStream.
|
|
|
359
|
+
|
|
|
360
|
+
|
|
|
361
|
+R.5 Known issues
|
|
|
362
|
+
|
|
|
363
|
+On every release, there are problems that has been identified by those working on the project and not yet resolved. In some cases, there are workarounds available. This page will include such information, specially valuable prior or immediately after a release. This content should provide context/summary of what is already available on the ticketing system.
|
|
|
364
|
+
|
|
|
365
|
+
|
|
|
366
|
+### Pj. BuildStream Project
|
|
|
367
|
+
|
|
|
368
|
+
|
|
|
369
|
+Contents related with the BuildStream Open Source project.
|
|
|
370
|
+
|
|
|
371
|
+Pj.1 Project Manifest (principles) , Mission and target audience definition
|
|
|
372
|
+
|
|
|
373
|
+Page describing the principles that drive the BuildStream community, its mission and the target audience in both, users and contributors.
|
|
|
374
|
+
|
|
|
375
|
+
|
|
|
376
|
+Pj.2 Governance + license + sponsors
|
|
|
377
|
+
|
|
|
378
|
+This page includes the governance aspects of the project, including the licenses and the project sponsors, as well as the relation with GNOME.
|
|
|
379
|
+
|
|
|
380
|
+
|
|
|
381
|
+Pj.3 How to participate
|
|
|
382
|
+
|
|
|
383
|
+This page includes the information required to participate in the project including the basic communication channels and links to read as initial steps.
|
|
|
384
|
+
|
|
|
385
|
+
|
|
|
386
|
+Pj.4 Meetings and events
|
|
|
387
|
+
|
|
|
388
|
+This page includes the events in which the BuildStream project participates and organizes. It should include also a list of the regular meetings, how to participate and where to find the logs.
|
|
|
389
|
+
|
|
|
390
|
+
|
|
|
391
|
+Pj.5 Community support and tools
|
|
|
392
|
+
|
|
|
393
|
+Description of the tools used by the BuildStream community, how to get access and description of the communication channels listed. This page complements Pj.3 since this page targets existing contributors instead of new ones.
|
|
|
394
|
+
|
|
|
395
|
+### Critical paths
|
|
|
396
|
+
|
|
|
397
|
+One day BuildStream will dominate the world. We will be able to look at behavioral flows on our site and see how people consume our contents and download/update our tool set just as the best retail company does. That would mean that we not just understand what our users and contributors want from us, but that we can anticipate what they might want from us tomorrow.
|
|
|
398
|
+
|
|
|
399
|
+To get there, we need to start today, simple but start.
|
|
|
400
|
+
|
|
|
401
|
+Having already defined our target audience to some extend was the first step. The content structure was the second one. The third one is to define our content considering a critical path, which is the journey we want to take our users through in order to consume our outcomes having a satisfactory experience. In other words, maximizing our conversion rate.
|
|
|
402
|
+
|
|
|
403
|
+In order to start simple, we will segment our audience in four groups, defining a critical path for each one of them. The target audiences are:
|
|
|
404
|
+* People unaware of BuildStream
|
|
|
405
|
+* People aware of BuildStream
|
|
|
406
|
+* BuildStream user
|
|
|
407
|
+* BuildStream contributor
|
|
|
408
|
+
|
|
|
409
|
+The two diagrams explain those critical paths:
|
|
|
410
|
+* The diagram "BuildStream_Content_Structure_critical_path_per_target.pdf"[2] defines the critical path per target audience group.
|
|
|
411
|
+* The diagram "BuildStream_Content_Structure_critical_path.pdf"[3] defines the critical path as a workflow.
|
|
|
412
|
+
|
|
|
413
|
+Each content unit is related with the one described in the content structure. Once we consolidate these critical paths, we will evaluate them and improve them. We will also add new ones once we have revisited our current target audience structure, lowering the granularity of our segmentation.
|
|
|
414
|
+
|
|
|
415
|
+### Evaluation of the conversion rate: metrics
|
|
|
416
|
+
|
|
|
417
|
+We will need to answer to following questions: are the BuildStream content helping to move people away from the Unaware group into the contributors segment group?
|
|
|
418
|
+
|
|
|
419
|
+Which means that we need a way to evaluate if the content structure, the content themselves and the critical paths work as expected. There are tools that provide metrics and dashboards to analyze the potential answers to these questions. Before we get to this point, we can evaluate the following:
|
|
|
420
|
+* Number of downloads of BuildStream.
|
|
|
421
|
+* Number of regular updates of BuildStream.
|
|
|
422
|
+* Hits per page.
|
|
|
423
|
+* Permanence time per page.
|
|
|
424
|
+* Source of the hit (search engine, social media, another BuildStream page...)
|
|
|
425
|
+
|
|
|
426
|
+which will provide us enough information to start learning about how well are we doing in terms of designing the contents the different target audiences need. Obviously the above information will only provide us trends in a blur picture, but overtime that is a good base to improve.
|
|
|
427
|
+
|
|
|
428
|
+
|
|
|
429
|
+## Further resources
|
|
|
430
|
+
|
|
|
431
|
+The following resources are recommended:
|
|
|
432
|
+[1] BuildStream_Content_Structure_diagram.pdf:
|
|
|
433
|
+
|
|
|
434
|
+[2] BuildStream_Content_Structure_critical_path_per_target.pdf:
|
|
|
435
|
+
|
|
|
436
|
+[3] BuildStream_Content_Structure_critical_path.pdf:
|
|
|
437
|
+
|
|
|
438
|
+[4] BuildStream_Content_Structure_all.pdf:
|
|
110
|
439
|
|
|
111
|
|
-### Update an engineering task / ticket
|
|
112
|
|
-
|
|
113
|
|
-Assuming the bulk of the work on engineering tasks takes places on Merge Requests (code), it is strongly recommended that you follow these advices:
|
|
114
|
|
-* Assign the ticket to you when you start working on it. More than one person can be assigned to a single task.
|
|
115
|
|
-* Assign the correct milestone and labels if they are not in place already.
|
|
116
|
|
- * If the task is being executed, please assign the label "Doing", removing the "ToDo" label.
|
|
117
|
|
- * Fill out the "Related Issues" field if there are other bugs or tasks that have a dependency or are related with the one it is being executed.
|
|
118
|
|
-* Update the ticket when a relevant event takes place. In any case, update the ticket every couple of days.
|
|
119
|
|
- * This is very important for others to follow up your work.
|
|
120
|
|
-
|
|
121
|
|
-### Close an engineering task
|
|
122
|
|
-
|
|
123
|
|
-(coming soon)
|
|
124
|
|
-
|
|
125
|
|
-## Bugs: best practices
|
|
126
|
|
-
|
|
127
|
|
-### Open/create a bug
|
|
128
|
|
-
|
|
129
|
|
-In order to open a new bug the best place is the green button at this page: <https://gitlab.com/BuildStream/buildstream/issues>. Please follow these considerations:
|
|
130
|
|
-* Use the Bug template. Choose it from the template menu when creating a new bug.
|
|
131
|
|
-* Fill out the information required. This is extremely important in the case of bugs. Developers will need to reproduce it in order to process it adequately.
|
|
132
|
|
- * Please fill out the milestone/version affected.
|
|
133
|
|
- * Refer to milestones adding the "%" symbol and selecting from the available options.
|
|
134
|
|
- * If the affected version is the current
|
|
135
|
|
-* Save the ticket.
|
|
136
|
|
-* Apply further metadata if you are sure about which labels to use.
|
|
137
|
|
- * If the bug shows up frequently and has a big impact in your everyday work or is present while performing a key action, please consider applying the label: high_impact. Otherwise, please do not apply it.
|
|
138
|
|
- * If you know the person responsible for analyzing/ processing the bug, please assign the bug to that person. Otherwise, leave it unassigned. The same policy applies to any topic labels.
|
|
139
|
|
- * Please remember that the Bug template already have the label "bug" assigned by default.
|
|
140
|
|
- * Do not assign any severity or status label unless you are going to work on it yourself. In case of doubt, apply the lowest value.
|
|
141
|
|
-* Further considerations:
|
|
142
|
|
- * Please refer to the considerations made for issues since they also apply to this case.
|
|
143
|
|
-
|
|
144
|
|
-### Update a bug
|
|
145
|
|
-
|
|
146
|
|
-Assuming the bulk of the work on bugs takes places on Merge Requests (code), it is strongly recommended that you follow these advices:
|
|
147
|
|
-* Assign the bug to you. More than one person can be assigned to a single bug.
|
|
148
|
|
-* Assign the correct milestone and labels if they are not in place already.
|
|
149
|
|
- * If the bug is being investigated or resolved, please assign the label "Doing", removing the "ToDo" label.
|
|
150
|
|
- * Fill out the "Related Issues" field if there are other bugs or tasks that have a dependency or are related with the one it is being executed.
|
|
151
|
|
-* Update the ticket when a relevant event takes place. In any case, update the ticket every couple of days.
|
|
152
|
|
- * This is very important for others to follow up your work.
|
|
153
|
|
-
|
|
154
|
|
-## Merge requests: best practices.
|
|
155
|
|
-
|
|
156
|
|
-These are the different policies that the project applies to merge requests.
|
|
157
|
|
-
|
|
158
|
|
-### Close a Bug
|
|
159
|
|
-
|
|
160
|
|
-(coming soon)
|
|
161
|
|
-
|
|
162
|
|
-## Merge requests (MR): best practices
|
|
163
|
|
-
|
|
164
|
|
-### Open/create a merge request
|
|
165
|
|
-
|
|
166
|
|
-Please read carefully the following policies before opening a new merge request. The best place to create a new merge request is this page: <https://gitlab.com/BuildStream/buildstream/merge_requests>. Please follow these considerations:
|
|
167
|
|
-* Use the default template.
|
|
168
|
|
-* Fill out the information required.
|
|
169
|
|
- * As in the case of the bugs, please be verbose. It will make the review process simpler and faster.
|
|
170
|
|
-* Save the merge request.
|
|
171
|
|
-* Apply further metadata if you are sure about which labels to use.
|
|
172
|
|
- * It is extremely important that you add to the merge request description the issue id/number this merge request affects to.
|
|
173
|
|
- * It is important to assign the merge request to a reviewer if you know who that person is. Please use the buildstream IRC channel to find out who that person is, if you can. Otherwise, leave it unassigned.
|
|
174
|
|
-* Further considerations:
|
|
175
|
|
- * We do not apply for now status labels to merge requests.
|
|
176
|
|
- * Severity labels will be applied in very specific cases only.
|
|
177
|
|
- * If you want to notify somebody about the merge request, please add his/her name as first comment, starting by the character "@". Try to avoid naming people for notification reasons in the merge request description field.
|
|
178
|
|
- * If your merge request remains unprocessed for over a week, please ask through IRC (#buildstream in irc.gonme.org) about it. It should be the exception but it might have been overlooked, remain unnoticed or the default reviewer is overloaded.
|
|
179
|
|
-
|
|
180
|
|
-### Update a merge request
|
|
181
|
|
-
|
|
182
|
|
-It is strongly recommended that you follow these advices:
|
|
183
|
|
-* Assign the Merge Request to you when you start working on it. Please remember than more than one person can be assigned to the MR.
|
|
184
|
|
-* Assign the correct milestone and labels if they are not in place already.
|
|
185
|
|
- * If the MR is in progress, please assign to it the label "Doing", removing the "ToDo" label if present.
|
|
186
|
|
- * every MR should be related in the description field to at least one engineering task or bug. Please check this is the case.
|
|
187
|
|
-* Update the MR when a relevant event takes place.
|
|
188
|
|
-
|
|
189
|
|
-## Suggest improvements or additions to the BuildStream policy
|
|
190
|
|
-
|
|
191
|
|
-If the suggestion refers to coding or hacking the BuildStream code related policies, please create a MR to the technical documentation: <https://gitlab.com/BuildStream/buildstream/tree/master/doc/source>
|
|
192
|
|
-
|
|
193
|
|
-If the suggestion refers to how to manage tickets, bugs or merge requests or any other topic not directly related with coding, please create a MR to this policy instead of editing this wiki page: <https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/BuildStream_policies.md>
|
|
194
|
|
-
|
|
195
|
|
-You can always send the proposal to the <mailto:buildstream-list gnome org> mailing list if any of the options above fits or you are unsure about what to do.
|
|
196
|
|
-
|
|
197
|
|
-### Close a Merge Request
|
|
198
|
|
-
|
|
199
|
|
-(coming soon)
|
