index.rst 10.1 KB
Newer Older
1
.. developer.skao.int documentation master file, created by
Marco Bartolini's avatar
Marco Bartolini committed
2
3
4
5
   sphinx-quickstart on Wed Dec 13 11:59:38 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Marco Bartolini's avatar
Marco Bartolini committed
6
7
8
9
10
11
12
13
14
.. HOME SECTION ==================================================

.. Hidden toctree to manage the sidebar navigation.

.. toctree::
  :maxdepth: 1
  :caption: Home
  :hidden:

Marco Bartolini's avatar
Marco Bartolini committed
15
16
17
SKA telescope developer portal
------------------------------

18
Welcome to the `Square Kilometre Array <http://www.skatelescope.org>`_ software
Marco Bartolini's avatar
Marco Bartolini committed
19
20
documentation portal. Whether you are a developer involved in SKA or you are
simply one of our many users, all of our software processes and projects are
21
documented or linked to in this portal.
Marco Bartolini's avatar
Marco Bartolini committed
22

23
The portal is frequently updated as the project evolves; if you feel that something is missing, please have a look at our :doc:`guide to contributing to the developer portal </contributor/contribute>`
Marco Bartolini's avatar
Marco Bartolini committed
24

25
If you're new to developing the SKA, please have a look at :doc:`our Onboarding material </getting-started/getting-started>` and the :doc:`guideance on setting up your development environment </getting-started/devenv-setup>`.
Marco Bartolini's avatar
Marco Bartolini committed
26

27
.. note::
28
   Please also read the :doc:`/policies/code-of-conduct`, which governs all SKA interactions.
Marco Bartolini's avatar
Marco Bartolini committed
29

30
What follows is a brief guide to the headings you'll find in the left-hand sidebar of this site. Feel free to explore!
Marco Bartolini's avatar
Marco Bartolini committed
31
32


33
34
Getting Started and the SKA Developer Community
-----------------------------------------------
Marco Bartolini's avatar
Marco Bartolini committed
35

36
37
38
39
This section is about getting you up and running. It contains the onboarding material for all new SKA developers, the general contribution guidelines when working on SKA projects, guidance on setting up your development environment, and a list of projects, so you know what the SKA is working on. There is also a wealth of information about our development tools and practices, which you can read as you start development work.


.. GETTING STARTED SECTION ==================================================
Marco Bartolini's avatar
Marco Bartolini committed
40
41
42
43
44

.. Hidden toctree to manage the sidebar navigation.

.. toctree::
  :maxdepth: 1
45
  :caption: Getting Started
Marco Bartolini's avatar
Marco Bartolini committed
46
47
  :hidden:

48
49
50
  getting-started/getting-started
  getting-started/contrib-guidelines
  getting-started/devenv-setup
Marco Bartolini's avatar
Marco Bartolini committed
51

52
53
54
- :doc:`getting-started/getting-started`
- :doc:`getting-started/contrib-guidelines`
- :doc:`getting-started/devenv-setup`
Marco Bartolini's avatar
Marco Bartolini committed
55

Marco Bartolini's avatar
Marco Bartolini committed
56

57
58
59
SKA Repositories
----------------

60
.. REPOSITORIES SECTION ========================================================
61
62
63
64
65

.. Hidden toctree to manage sidebar navigation

.. toctree::
  :maxdepth: 1
66
  :caption: Repositories
67
68
  :hidden:

69
  projects/area
70
71
72
  projects/list
  projects/create-new-project
  projects/licensing
Marco Bartolini's avatar
Marco Bartolini committed
73

Marco Bartolini's avatar
Marco Bartolini committed
74
75
76
77
78
79
80
81
82
.. DEVELOPMENT TOOLS SECTION ==================================================

.. Hidden toctree to manage the sidebar navigation.

.. toctree::
  :maxdepth: 1
  :caption: Development tools
  :hidden:

Marco Bartolini's avatar
Marco Bartolini committed
83
  tools/git
84
  tools/jira
85
  tools/ci-cd
vla22's avatar
vla22 committed
86
87
  tools/bdd-test-context
  tools/bdd-walkthrough
88
  tools/test-infrastructure
89
90
  tools/containers
  tools/documentation
91
92
93
94
  tools/software-package-release-procedure
  tools/logging-format
  tools/monitoring-dashboards/monitoring-dashboards
  tools/reporting-bugs
95
  tools/codeguides
96
  tools/dev-faq
97
98
99

Development tools and practices
-------------------------------
100
101
SKA git repositories
====================
Marco Bartolini's avatar
Marco Bartolini committed
102

103
104
The SKA uses git as its distributed version control system, and all SKA code shall be hosted in an SKA organisation. The gitlab organization *ska-telescope* can be found at https://gitlab.com/ska-telescope. All SKA developers
must have a gitlab account and be added to the organisation. See :doc:`/tools/git` for further details.
Marco Bartolini's avatar
Marco Bartolini committed
105

Hélder Ribeiro's avatar
Hélder Ribeiro committed
106
107
Working with SKA Jira
=====================
Marco Bartolini's avatar
Marco Bartolini committed
108

109
Every team is tracking daily work in a team-based project on our JIRA server at https://jira.skatelescope.org. Our internal wiki, Confluence, has guidance on how we use JIRA.  We rely on integrations between GitLab and JIRA to manage our work.
Marco Bartolini's avatar
Marco Bartolini committed
110

111
112
- :doc:`tools/jira`

113
114
CI/CD: Continuous Integration and Deployment
============================================
115

116
CI/CD is at the heart of SKA development, and we use GitLab's automation extensively, so we can test and deploy our software more efficiently.
117

118
- :doc:`tools/ci-cd`
119

120
121
Testing
=======
122

vla22's avatar
vla22 committed
123
Tests are a key part of producing working software. We suggest you look at our :doc:`policies/ska-testing-policy-and-strategy`, and our :doc:`tools/bdd-test-context` and :doc:`tools/bdd-walkthrough`.
124

125
Test Infrastructure
126
127
===================

128
To support our testing and CI/CD pipelines, we have the multiple kubernetes clusters configured to allow testing to happen.
129

130
- :doc:`tools/test-infrastructure`
131
- :doc:`tools/monitoring-dashboards/stfc-performance-env`
132

133
134
Containerisation
================
135

136
To facilitate code portability and reliability and test running, we use containers. We also use kubernetes as our container orchestration system.
137

138
139
140
141
142
143
144
- :doc:`tools/containers`
- :doc:`tools/containers/containerisation-standards`
- :doc:`tools/containers/kubernetes-introduction`
- :doc:`tools/containers/orchestration-guidelines`
- :doc:`tools/containers/multitenancy`
- :doc:`tools/containers/docker-proxy-cache`
- :doc:`tools/containers/uploading-docker-nexus`
Katleho Madisa's avatar
Katleho Madisa committed
145

146
147
Documentation
=============
Katleho Madisa's avatar
Katleho Madisa committed
148

149
While we prefer working code over documentation (as Agile developers), we also recognise that this is a large and long-lived project, so documentation has an important place.
Katleho Madisa's avatar
Katleho Madisa committed
150

151
- :doc:`tools/documentation`
152

153
154
Package Release Process
=======================
155

156
What you need to know in order to release an SKA software package.
157

158
- :doc:`tools/software-package-release-procedure`
159

160
161
Logging
=======
162

163
Making sure your software project outputs useful logs for the SKA
164

165
- :doc:`tools/logging-format`
J. Bruno Morgado's avatar
J. Bruno Morgado committed
166

167
168
Monitoring Dashboards
=====================
J. Bruno Morgado's avatar
J. Bruno Morgado committed
169

170
You've deployed your code on one of our test systems. Now you want to monitor it.
J. Bruno Morgado's avatar
J. Bruno Morgado committed
171

172
- :doc:`tools/monitoring-dashboards/monitoring-dashboards`
173

174
175
Bug Reporting
=============
176

177
What to do when you find a bug in SKA code.
178

179
- :doc:`tools/reporting-bugs`
180

181
182
Coding Guidelines
=================
Marco Bartolini's avatar
Marco Bartolini committed
183

184
Guidelines to the coding standards we apply in the SKA. Not available for all languages.
Marco Bartolini's avatar
Marco Bartolini committed
185

186
187
188
189
- :doc:`tools/codeguides`
- :doc:`tools/codeguides/cplusplus-codeguide`
- :doc:`tools/codeguides/javascript-codeguide`
- :doc:`tools/codeguides/python-codeguide`
190
- :doc:`tools/codeguides/vhdl-codeguide`
Marco Bartolini's avatar
Marco Bartolini committed
191

192
193
FAQ
===
Marco Bartolini's avatar
Marco Bartolini committed
194

195
Questions frequently asked by developers.
Marco Bartolini's avatar
Marco Bartolini committed
196

197
- :doc:`tools/dev-faq`
Marco Bartolini's avatar
Marco Bartolini committed
198

199
.. POLICES & PROCEDURES SECTION ==================================================
Marco Bartolini's avatar
Marco Bartolini committed
200
201
202
203
204

.. Hidden toctree to manage the sidebar navigation.

.. toctree::
  :maxdepth: 1
205
  :caption: Policies and Procedures
Marco Bartolini's avatar
Marco Bartolini committed
206
207
  :hidden:

208
  policies/code-of-conduct
209
  policies/fundamental-sw-requirements
Marco Bartolini's avatar
SST-530    
Marco Bartolini committed
210
  policies/sw-quality-assurance
211
  policies/sw-dev-security
212
213
214
215
  policies/definition-of-done
  policies/ska-testing-policy-and-strategy
  policies/decision-making
  policies/incident-management
Marco Bartolini's avatar
Marco Bartolini committed
216

217
218
Policies and Procedures
-----------------------
219

220
221
Fundamental SKA Software & Hardware Description Language Standards
==================================================================
222

223
These standards underpin all SKA software development. The canonical copy is
224
`held in eB <https://ska-aw.bentley.com/SKAProd/Search/QuickLink.aspx?n=SKA-TEL-SKO-0000661&t=3&d=&sc=Global&i=view>`_,
225
but the essential information is here:
226

227
- :doc:`policies/fundamental-sw-requirements`
228

229
230
231
232
233
234
235
236
237
238
239
Software Product Quality Assurance plan
=======================================

This Software Product Quality Assurance Plan (SPQAP) defines the Quality Assurance requirements and management 
activities for the development of software by the Agile Development Teams through the PSSC Contracting arrangements, 
and the delivery of the software by the SKAO.

This document is a mapping to the SKA Product Quality Assurance (PQA) Plan, that describes the roles and 
responsibilities of the SKAO and the Contractors and provides an itemised response to the Product Quality Assurance Management, 
and the PQA Requirements sections.

Marco Bartolini's avatar
SST-530    
Marco Bartolini committed
240
- :doc:`policies/sw-quality-assurance`
241

242
243
244
245
246
247
248
249
250
Software Development Security Policy 
====================================

Most of the software used for the control and operation of the SKAO telescopes will be developed by SKA Community members and contributors. 
To ensure the smooth operation of the SKAO and minimise the risk of software vulnerabilities, information security must be incorporated 
within the software development lifecycle of SKAO software. This document describes how this must be achieved. 

- :doc:`policies/sw-dev-security`

251
252
253
254
255
256
Definition of Done
==================

The definition of done is used to guide teams in planning and estimating the size of stories and features:

- :doc:`policies/definition-of-done`
257

258
259
Incident Management
===================
Marco Bartolini's avatar
Marco Bartolini committed
260

261
The incident management workflow is used to guide teams in dealing with anomolous conditions that lead to some form of service outage, unexpected system behaviour or degraded system performance:
Marco Bartolini's avatar
Marco Bartolini committed
262

vla22's avatar
vla22 committed
263
- :doc:`policies/incident-management`
264
265
266
267
268
269
270
271
272
273

.. RECOMMENDED READING SECTION ==================================================

.. Hidden toctree to manage the sidebar navigation.

.. toctree::
  :maxdepth: 1
  :caption: Recommended Reading
  :hidden:

274
275
276
  recommended-reading/system-design
  recommended-reading/programming
  recommended-reading/programming-languages
277

vla22's avatar
vla22 committed
278
.. ABOUT SECTION ==================================================
Vinod Sathe's avatar
Vinod Sathe committed
279
280
281
282
283

.. Hidden toctree to manage the sidebar navigation.

.. toctree::
  :maxdepth: 1
vla22's avatar
vla22 committed
284
  :caption: About the SKA
Vinod Sathe's avatar
Vinod Sathe committed
285
286
  :hidden:

287
288
289
290
  about/ska-org
  about/safe-for-ska
  about/followus-env
  about/teams-responsibilities
vla22's avatar
vla22 committed
291
292
293

About the SKA
-------------
Vinod Sathe's avatar
Vinod Sathe committed
294

295
296
297
298
299
For information about the SKA, have a look at this section.

- :doc:`about/ska-org`
- :doc:`about/safe-for-ska`
- :doc:`about/followus-env`
300
- :doc:`about/teams-responsibilities`
301

Vinod Sathe's avatar
Vinod Sathe committed
302

303
- :doc:`about/followus-env`
Vinod Sathe's avatar
Vinod Sathe committed
304

vla22's avatar
vla22 committed
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322

.. CONTRIBUTOR SECTION ==================================================

.. Hidden toctree to manage the sidebar navigation.

.. toctree::
  :maxdepth: 1
  :caption: Contribute to the Developer Portal
  :hidden:

  contributor/contribute

Contribute to the SKA Developer Portal
--------------------------------------

We encourage all members of the development community to submit improvements to the Developer Portal. These pages describe how you can contribute changes to the Developer Portal.

- :doc:`contributor/contribute`