diff --git a/docs.json b/docs.json index b224a19557..6e8f065a0d 100644 --- a/docs.json +++ b/docs.json @@ -730,6 +730,34 @@ "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/reference/configuration/bootloader.md" } ] + }, + { + "title": "Contributing", + "intro": { + "type": "markdown", + "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/reference/contributing/guidelines/guidelines.md" + }, + "sources": [{ + "type": "markdown", + "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/reference/contributing/guidelines/license.md" + }, + { + "type": "markdown", + "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/reference/contributing/guidelines/style.md" + }, + { + "type": "markdown", + "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/reference/contributing/guidelines/design_guidelines.md" + }, + { + "type": "markdown", + "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/reference/contributing/guidelines/workflow.md" + }, + { + "type": "markdown", + "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/reference/contributing/guidelines/ci.md" + } + ] } ] }, diff --git a/docs/reference/contributing/guidelines/ci.md b/docs/reference/contributing/guidelines/ci.md new file mode 100644 index 0000000000..5d41ce8184 --- /dev/null +++ b/docs/reference/contributing/guidelines/ci.md @@ -0,0 +1,56 @@ +

Continuous integration

+ +Continuous integration (CI) means mainly automatic testing for pull requests. + +### Travis CI + +In Mbed OS [Travis CI](https://travis-ci.org/ARMmbed/mbed-os) is used as primary automatic testing and checking run environment. + +Travis configuration is located in the [.travis.yml](https://github.com/ARMmbed/mbed-os/blob/master/.travis.yml) file in Mbed OS root directory. Mbed OS uses public travis so test results are publicly available and there are public [documentation available](https://docs.travis-ci.com/). + +#### Tests + +- **continuous-integration/travis-ci/pr** - Run other testing jobs. +- **travis-ci/astyle** - Check code style using [astyle](http://astyle.sourceforge.net/). +- **travis-ci/docs** - [Doxygen](http://www.doxygen.org/) and naming checks: + - Assert that the Doxygen build produces no warnings. + - Assert that all binary libraries are named correctly. + - Assert that all assembler files are named correctly. +- **travis-ci/events** - Check that Mbed OS compiles and run events tests. +- **travis-ci/gitattributestest** - Check there are no changes after clone. This checks that `.gitattributes` is used correctly. +- **travis-ci/licence_check** - Check there is no GPL licence text in the code. +- **travis-ci/littlefs** - Test littlefs without embedded hardware. +- **travis-ci/tools-py2.7** - Run Python tools tests with Python 2.7. + +### Jenkins + +We use [Jenkins](https://jenkins.io/) as an internal testing and checking environment. We execute tests that have special requirements for the execution enviroment in our internal Jenkins. In most cases, we publish test logs. + +How it works: + +- Jenkins uses a [scripted pipeline syntax](https://jenkins.io/doc/book/pipeline/). +- Jenkins scripts are not publicly available. There is a Jenkinsfile in the Mbed OS root folder, but that is just a trigger for tests. +- Jenkins selects required tests dynamically based on the code changes. For example, no tests execute if only markdown (.md) files change. +- Jenkins runs a first small number of tests to provide fast feedback, and then it runs additional tests. + +#### Tests + +- **continuous-integration/jenkins/pr-head** - Jenkins main pipeline script execution status. +- **jenkins-ci/build-ARM** - Build Mbed OS and examples with [ARM compiler](https://developer.arm.com/products/software-development-tools/compilers/arm-compiler). Related commands: + - `mbed test --compile -t -m `. + - `python -u mbed-os/tools/test/examples/examples.py compile --mcu `. +- **jenkins-ci/build-GCC_ARM** - Build Mbed OS and examples with GCC_ARM. +- **jenkins-ci/build-IAR** - Build Mbed OS and examples with IAR. +- **jenkins-ci/cloud-client-test** - Test the change with [mbed-cloud-client](https://github.com/ARMmbed/mbed-cloud-client) using the [mbed-cloud-client-example](https://github.com/ARMmbed/mbed-cloud-client-example). +- **jenkins-ci/dynamic-memory-usage** - Report dynamic memory use compared to the master branch. +- **jenkins-ci/exporter** - Export and build exported code. Related commands: + - `python -u mbed-os/tools/test/examples/examples.py export --mcu `. +- **jenkins-ci/greentea-test** - Run [greentea tests](/docs/tools/testing/testing_greentea.html). +- **jenkins-ci/mbed2-build-ARM** - Build Mbed OS 2 with [ARM compiler](https://developer.arm.com/products/software-development-tools/compilers/arm-compiler). Related commands: + - `python tools/build_release.py -p -t `. +- **jenkins-ci/mbed2-build-GCC_ARM** - Build Mbed OS 2 with GCC_ARM. +- **jenkins-ci/mbed2-build-IAR** - Build Mbed OS 2 with IAR. +- **jenkins-ci/unittests** - Run [unit tests](/docs/tools/testing/unit_testing.html). +- **tools-test-linux** - Test that tools work on Linux. +- **tools-test-mac** - Test that tools work on macOS. +- **tools-test-windows** - Test that tools work on Windows. diff --git a/docs/reference/contributing/guidelines/workflow.md b/docs/reference/contributing/guidelines/workflow.md index 93e56ffced..9914e02ec6 100644 --- a/docs/reference/contributing/guidelines/workflow.md +++ b/docs/reference/contributing/guidelines/workflow.md @@ -187,7 +187,7 @@ Time: 3 days for reviewers to leave feedback after the maintainers add the "need #### The CI (Continuous Integration) testing -There are many CI systems available. Which CI tests we run against a particular pull request depends on the effect that pull request has on the code base. Irrespective of which CI tests run, Mbed OS has an all green policy, meaning that all the CI jobs that are triggered must pass before we merge the pull request. +There are many [CI systems available](../contributing/guidelines/ci.html) for testing Mbed OS pull requests and braches. Which CI tests we run against a particular pull request depends on the effect that pull request has on the code base. Irrespective of which CI tests run, Mbed OS has an all green policy, meaning that all the CI jobs that are triggered must pass before we merge the pull request. Label: `needs: review` Time: 1 day for CI to complete and report back results.