index.rst 9.15 KB
Newer Older
Marco Bartolini's avatar
Marco Bartolini committed
1 2 3 4 5
.. developer.skatelescope.org documentation master file, created by
   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

56
A list of the tools we are using to collaborate, together with guidance on how to use them can be found at this confluence page: `SKA Guidelines to Remote Working <https://confluence.skatelescope.org/display/SKAIT/SKA+Guidelines+to+Remote+Working>`_ (requires an SKA Confluence account).
Marco Bartolini's avatar
Marco Bartolini committed
57

58 59 60
SKA Repositories
----------------

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

.. Hidden toctree to manage sidebar navigation

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

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

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

.. Hidden toctree to manage the sidebar navigation.

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

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

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

104 105
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
106

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

110
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
111

112 113
- :doc:`tools/jira`

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

117
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.
118

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

121 122
Testing
=======
123

vla22's avatar
vla22 committed
124
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`.
125 126
 
Test Infrastructure
127 128
===================

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

131
- :doc:`tools/test-infrastructure`
132
- :doc:`tools/monitoring-dashboards/ait-performance-env`
133

134 135
Containerisation
================
136

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

139 140 141 142 143 144 145
- :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
146

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

150
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
151

152
- :doc:`tools/documentation`
153

154 155
Package Release Process
=======================
156

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

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

161 162
Logging
=======
163

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

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

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

171
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
172

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

175 176
Bug Reporting
=============
177

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

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

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

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

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

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

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

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

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

.. Hidden toctree to manage the sidebar navigation.

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

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

216 217
Definition of Done
==================
218

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

221
- :doc:`policies/definition-of-done`
222

223 224
Fundamental SKA Software & Hardware Description Language Standards
==================================================================
225

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

230
- :doc:`policies/fundamental-sw-requirements`
231 232


233 234
Incident Management
===================
Marco Bartolini's avatar
Marco Bartolini committed
235

236
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
237

vla22's avatar
vla22 committed
238
- :doc:`policies/incident-management`
239 240 241 242 243 244 245 246 247 248

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

.. Hidden toctree to manage the sidebar navigation.

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

249 250 251
  recommended-reading/system-design
  recommended-reading/programming
  recommended-reading/programming-languages
252

vla22's avatar
vla22 committed
253
.. ABOUT SECTION ==================================================
Vinod Sathe's avatar
Vinod Sathe committed
254 255 256 257 258

.. Hidden toctree to manage the sidebar navigation.

.. toctree::
  :maxdepth: 1
vla22's avatar
vla22 committed
259
  :caption: About the SKA
Vinod Sathe's avatar
Vinod Sathe committed
260 261
  :hidden:

262 263 264 265
  about/ska-org
  about/safe-for-ska
  about/followus-env
  about/teams-responsibilities
vla22's avatar
vla22 committed
266 267 268

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

270 271 272 273 274
For information about the SKA, have a look at this section.

- :doc:`about/ska-org`
- :doc:`about/safe-for-ska`
- :doc:`about/followus-env`
275
- :doc:`about/teams-responsibilities`
276

Vinod Sathe's avatar
Vinod Sathe committed
277

278
- :doc:`about/followus-env`
Vinod Sathe's avatar
Vinod Sathe committed
279

vla22's avatar
vla22 committed
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297

.. 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`