Verified Commit 3c47ba9a authored by vla22's avatar vla22
Browse files

SP-1466 Fix paths broken by file renaming and by project reorganisation.

Remove some ".. doctest-skip-all" declarations.
parent 170d1f28
Pipeline #246563829 failed with stages
in 1 minute and 34 seconds
......@@ -13,8 +13,10 @@ License File
Every software repository shall be licensed according to the SPDX standard.
Every repository shall contain a LICENSE file in its top directory, indicating the copyright holder and the license used for the software in its full textual representation.
Licenses
========
.. _ok-licenses:
Acceptable License
==================
SKA office will automatically accept the BSD 3-clause new LICENSE and any exception to this shall be justified and agreed with SKA office Software Quality Assurance engineer. A template of the license is presented at the end of this page.
Existing repositories already published with permissive licenses such as Apache 2.0 or MIT licenses will also be accepted as part of the handover procedure, while new repositories are encouraged to adopt the recommended BSD license.
......
.. _policies:
SKA Code of Conduct
-------------------
......
.. _policies:
SKA developer community decision making process
-----------------------------------------------
......
.. _policies:
Definition of Done
==================
......@@ -11,28 +13,28 @@ Issue Type Definition of Done
=================== =========================================================================================================================
**Story/Enabler** **Code**
* Supplied with an `acceptable license <https://developer.skatelescope.org/en/latest/projects/licensing.html?#licensing-a-project>`_
* Adheres to SKA language `specific style <https://developer.skatelescope.org/en/latest/search.html?q=coding%2Bguidelines>`_
* Checked into SKA repository with `reference <https://developer.skatelescope.org/en/latest/tools/jira.html>`_ to a Jira issue ID
* Passes the CI/CD pipeline including compiling cleanly and being linted with no `warnings <https://developer.skatelescope.org/en/latest/tools/continuousintegration.html?#linting>`_
* Unit and module `tests <https://developer.skatelescope.org/en/latest/tools/continuousintegration.html?#test>`_ pass with adequate coverage (>= 75% with appropriate exclusions for boiler-plate code)
* Component, integration and system `tests <https://developer.skatelescope.org/en/latest/tools/continuousintegration.html?#test>`_ (appropriate for the context) pass
* Regression `tests <https://developer.skatelescope.org/en/latest/tools/continuousintegration.html?#test>`_ pass
* Supplied with an :ref:`ok-licenses`.
* Adheres to SKA language :doc:`specific style </tools/codeguides>`.
* Checked into SKA repository with a :doc:`reference </tools/jira>` to a JIRA ticket ID.
* Passes the CI/CD pipeline including compiling cleanly and being linted with no warnings: :ref:`linting`.
* Unit and module :ref:`tests <tests>` pass with adequate coverage (>= 75% with appropriate exclusions for boiler-plate code).
* Component, integration and system :ref:`tests <tests>` (appropriate for the context) pass.
* Regression :ref:`tests <tests>` pass.
`Code Documentation <https://developer.skatelescope.org/en/latest/projects/document_project.html#documenting-a-project>`_
:doc:`Code Documentation </tools/documentation>`
* Exposed `Public API <https://developer.skatelescope.org/en/latest/projects/document_project.html#documenting-the-public-api>`_ (where applicable) is cleanly documented
* Documented inline according to `language specific standards <https://developer.skatelescope.org/en/latest/search.html?q=coding%2Bguidelines>`_
* Deployed to externally visible website accessible via the `developer portal <https://developer.skatelescope.org/en/latest/projects/document_project.html#integrating-into-the-developer-portal>`_
* Exposed Public :ref:`API <API>` (where applicable) is cleanly documented.
* Documented inline according to :doc:`language specific standards </tools/codeguides>`.
* Deployed to externally visible website accessible via the :ref:`dev-portal-integration`.
**Integration**
* Deployed to a `continuous integration <https://developer.skatelescope.org/en/latest/tools/continuousintegration.html#continuous-integration>`_ environment (staging environment during Construction)
* `Migrations <https://developer.skatelescope.org/en/latest/projects/create_new_project.html?highlight=migration#repository-contents>`_ are implemented with defined automated processes for roll-forward and rollback as appropriate
* Deployed to a :doc:`/tools/ci-cd/continuous-integration` environment (staging environment during Construction).
* Migrations are implemented with defined automated processes for roll-forward and rollback as appropriate.
**Process**
* Peer-reviewed and integrated into the main branch via Gitlab `merge-request <https://developer.skatelescope.org/en/latest/tools/git.html#merge-requests>`_ process
* Peer-reviewed and integrated into the main branch via GitLab :ref:`merge-request`.
* Relevant `NFRs <https://confluence.skatelescope.org/display/SWSI/Requirements>`_ are met
* Satisfies acceptance criteria
* Accepted by Product Owner
......@@ -56,11 +58,11 @@ Issue Type Definition of Done
=================== =========================================================================================================================
**Feature/Enabler** **Child Stories/Enablers**
* Completed by all teams and integrated in an `integration environment <https://developer.skatelescope.org/en/latest/development/getting_started.html#incorporate-my-project-into-the-integration-environment>`_ (staging environment during Construction)
* Completed by all teams and integrated in an :ref:`integration environment <verify-k8s>` (staging environment during Construction).
**Documentation**
* `Solution Intent <https://confluence.skatelescope.org/display/SWSI/Solution+Intent+Home>`_ updated to reflect the actual implementation
* `Solution Intent <https://confluence.skatelescope.org/display/SWSI/Solution+Intent+Home>`_ or project documentation updated to reflect the actual implementation.
**Process**
......@@ -88,11 +90,11 @@ Issue Type Definition of Done
====================== =========================================================================================================================
**Capability/Enabler** **Child Stories/Enablers**
* Completed by all ARTs and integrated in an `integration environment <https://developer.skatelescope.org/en/latest/development/getting_started.html#incorporate-my-project-into-the-integration-environment>`_ (staging environment during Construction)
* Completed by all ARTs and integrated in an :ref:`integration environment <verify-k8s>` (staging environment during Construction)
**Documentation**
* `Solution Intent <https://confluence.skatelescope.org/display/SWSI/Solution+Intent+Home>`_ updated to reflect the actual implementation
* `Solution Intent <https://confluence.skatelescope.org/display/SWSI/Solution+Intent+Home>`_ or project documentation updated to reflect the actual implementation
**Process**
......
......@@ -414,7 +414,7 @@ shall include:
Deployment may require the use of the host based software
delivered as part of the LMC system.
12. The ability to log diagnostic information using :doc:`logging-format`.
12. The ability to log diagnostic information using :doc:`/tools/logging-format`.
13. The ability, dynamically at runtime, to suppress or select logging
of messages at different Syslog severity levels on at least a
......
......@@ -425,6 +425,7 @@ stakeholder in SKA.
Some of these metrics are collected and displayed by the ARGOS system
in https://argos.engageska-portugal.pt
(username=viewer, password=viewer).
See :doc:`/tools/monitoring-dashboards/monitoring-dashboards` for more information.
5 Testing strategy
......
......@@ -4,4 +4,4 @@ Programming
* `Code complete <https://www.amazon.co.uk/Code-Complete-Practical-Handbook-Construction/dp/0735619670/ref=sr_1_1?ie=UTF8&qid=1543264012&sr=8-1&keywords=code+complete+2>`_ is a practical introduction to software craftmanship.
* `The pragmatic programmer <https://pragprog.com/book/tpp/the-pragmatic-programmer>`_ is a good introduction to sound programming practices.
* `Clean code <https://www.amazon.co.uk/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882/ref=sr_1_2?ie=UTF8&qid=1543264012&sr=8-2>`_ introduces quality software practices showcasing different examples and good principles from the agile world.
* `Extreme programming explained <https://www.amazon.co.uk/Extreme-Programming-Explained-Embrace-Change/dp/0321278658>`_ can be extremely useful to teams and developers embracing a more agile way of working for the first time.
\ No newline at end of file
* `Extreme programming explained <https://www.amazon.co.uk/Extreme-Programming-Explained-Embrace-Change/dp/0321278658>`_ can be extremely useful to teams and developers embracing a more agile way of working for the first time.
:: _ci_cd:
.. _ci_cd:
CI/CD
*****
How the SKA does Continuous Integration and Deployment, using GitLab's tools.
These pages describe the full :doc:`CI process </tools/ci-cd/continuous-integration>`, the :doc:`/tools/ci-cd/gitlab-variables` used for projects, and a mirror of the :doc:`/tools/ci-cd/ci-dashboard`.
.. toctree::
:maxdepth: 1
:hidden:
ci-cd/continuous-integration
ci-cd/gitlab-variables
ci-cd/ci-dashboard
......@@ -17,4 +17,6 @@ False False False
True False True
False True True
True True True
===== ===== ======
\ No newline at end of file
===== ===== ======
.. <script type="text/javascript" src="../_static/js/gitlab.js"></script>
.. _CI:
.. _ci-cd:
======================
Continuous Integration
......@@ -220,7 +220,7 @@ Build
"""""
The build stage packages/compiles the software project into distributable units of software.
The project will be checked out at the git commit hash. This specific version of the code must then be built. Failing the build stage will stop the further steps from being executed. Where possible Semantic Versioning should be used.
To create a release a git tag should be used. `See Release Procedure <http://developer.skatelescope.org/en/latest/development/software_package_release_procedure.html>`_.
To create a release a git tag should be used. See :doc:`/tools/software-release-package-procedure` for details.
Input
Git commit hash
......@@ -230,6 +230,7 @@ Output
These must be stored as part of the artifacts and will then be available to subsequent jobs.
One could also store metadata together with the artefact, such as a hash of the binary artefact. This should be provided by our artefact registry.
.. _linting:
Linting
"""""""
......@@ -240,10 +241,12 @@ Input
Output
Quality analysis results in JUnit format.
.. _tests:
Test
""""
The test stage must install/make use of the packages created during the build stage and execute tests on the installed software. Tests should be grouped into Fast / Medium / Slow / Very Slow categories.
The test stage must install/make use of the packages created during the build stage and execute tests on the installed software. Tests should be grouped into Fast / Medium / Slow / Very Slow categories. For more details, read the :doc:`/policies/ska-testing-policy-and-strategy`.
Input
The output from the Build stage. E.g .deb or .whl or docker image.
......@@ -308,7 +311,7 @@ Output
Documentation
"""""""""""""
Currently the documentation is generated by the “readthedocs” online service.
The list of SKA projects available :doc:`here </projects/list>`.
The list of SKA projects available :doc:`/getting-started/projects/list`.
The project documentation will be updated and accessible at the following URL
\https://developer.skatelescope.org/projects/<PROJECT>
E.g `lmc-base-classes <https://developer.skatelescope.org/projects/lmc-base-classes>`_
......@@ -379,7 +382,7 @@ Kubernetes based Runners Architecture
------------------------------------------------------------------
GitLab runners are orchestrated by Kubernetes cluster. They could be deployed to any Kubernetes clusters with following the instructions on deploy-gitlab-runners repository. The main architecture is illustrated below.
|runners_on_kubernetes|
|runners-on-kubernetes|
Features
________
......@@ -426,28 +429,28 @@ The conversion process is relatively straightforward, requiring two steps:
This converts the :code:`docker-compose.yml` file to files that you can use with :code:`kubectl`. To make sure that the transition will work in the runner cluster you can test locally with Minikube. If it works on your local Minikube then it will work in the kubernetes runner cluster.
.. |image0| image:: media/image1.png
.. |image0| image:: ../media/image1.png
:width: 6.27083in
:height: 0.83333in
.. |image1| image:: media/image6.png
.. |image1| image:: ../media/image6.png
:width: 6.27083in
:height: 3.86111in
.. |image2| image:: media/image4.png
.. |image2| image:: ../media/image4.png
:width: 6.27083in
:height: 4.27778in
.. |image3| image:: media/image5.png
.. |image3| image:: ../media/image5.png
:width: 6.27083in
:height: 5.25000in
.. |image4| image:: media/image3.png
.. |image4| image:: ../media/image3.png
:width: 6.27083in
:height: 4.47222in
.. |image5| image:: media/image2.png
.. |image5| image:: ../media/image2.png
:width: 6.27083in
:height: 2.88889in
.. |image6| image:: media/image7.png
.. |image6| image:: ../media/image7.png
:width: 6.27083in
:height: 4.63889in
.. |image7| image:: media/image0.png
.. |image7| image:: ../media/image0.png
:width: 6.27083in
:height: 4.63889in
.. |runners_on_kubernetes| image:: media/runners_on_kubernetes.png
\ No newline at end of file
.. |runners-on-kubernetes| image:: ../media/runners-on-kubernetes.png
.. doctest-skip-all
.. _gitlab-variables:
***********************
......@@ -17,7 +16,7 @@ The variables are set under the
.. _figure-1-gitlab-variables:
.. figure:: images/gitlab-variables.png
.. figure:: ../images/gitlab-variables.png
:scale: 55%
:alt: GitLab Variables
:align: center
......
:: _codeguides:
.. _codeguides:
Coding guidelines
*****************
.. toctree::
:maxdepth: 1
codeguides/cplusplus-codeguide
codeguides/javascript-codeguide
codeguides/python-codeguide
codeguides/vhdl-codeguide
.. doctest-skip-all
.. _cplusplus-code-guide:
.. _codeguides:
************************
C++ Coding Guidelines
......@@ -67,7 +66,7 @@ The Source Tree
^^^^^^^^^^^^^^^
Our recommended source tree structure follows:
.. literalinclude:: cpp_source_tree.txt
.. literalinclude:: cpp-source-tree.txt
A number of design decisions have been made here:
......@@ -377,7 +376,7 @@ a new derived instance of an hello world. I have included a test and I checked
locally that all the existing code built - after the merge request is started
GitLab gives the following report:
.. image:: merge-request.png
.. image:: ../images/merge-request.png
You can see that there is not much detail - but the tests results are parsed and any differences are noted.
......@@ -406,7 +405,7 @@ Note that the atifacts step this allows the results to be accessed via the pipel
.. note:: As far as we know there is no plugin for the coverage artifacts generated by gcov
.. image:: coverage.png
.. image:: ../images/coverage.png
But you can access the artifact from the pipeline.
......
:: _containers:
.. _containers:
Containers: containerisation and deployment
*******************************************
.. toctree::
:maxdepth: 1
containers/containerisation-standards
containers/docker-proxy-cache
containers/kubernetes-introduction
containers/multitenancy
containers/orchestration-guidelines
containers/uploading-docker-nexus
......@@ -42,6 +42,8 @@ The standards are broken down into the following areas:
Throughout this documentation, `Docker <https://docs.docker.com/>`_ is used as the reference implementation with the canonical version being Docker 18.09.4 CE API version 1.39, however the aim is to target compliance with the OCI specifications so it is possible to substitute in alternative Container Engines, and image build tools that are compatible.
.. _container-cheat-sheet:
Cheatsheet
==========
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment