From 6eee41a5fedc100afb8bfb32a433e860940d0336 Mon Sep 17 00:00:00 2001 From: James Foster Date: Mon, 5 Oct 2020 19:14:04 -0700 Subject: [PATCH] Update docs to explain purpose of SampleProjects (#156) - Update docs to explain purpose of SampleProjects and avoid impression that they are templates to be followed too closely. - Provide alternative `bundle install` command (the original one doesn't work on macOS 10.16). - Correct location for your project. --- README.md | 6 +++--- SampleProjects/DoSomething/test/README.md | 8 +++++--- SampleProjects/README.md | 6 +++--- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 423a8c03..27b8ce5e 100644 --- a/README.md +++ b/README.md @@ -82,10 +82,10 @@ vendor ### Installing the Dependencies -Fulfilling the `arduino_ci` library dependency is as easy as running this command: - +Fulfilling the `arduino_ci` library dependency is as easy as running either of these two commands: ``` -$ bundle install +$ bundle install # adds packages to global library (may require admin rights) +$ bundle install --path vendor/bundle # adds packages to local library ``` diff --git a/SampleProjects/DoSomething/test/README.md b/SampleProjects/DoSomething/test/README.md index 6e099ec6..1c958086 100644 --- a/SampleProjects/DoSomething/test/README.md +++ b/SampleProjects/DoSomething/test/README.md @@ -1,7 +1,9 @@ -# Purpose +## Purpose -These files are designed to test the Ruby gem itself, such that its basic tasks of library installation and compilation can be verified. (i.e., use minimal C++ files -- feature tests for C++ unittest/arduino code belong in `../TestSomething/test/`). +These files are designed to test the testing framework (the Ruby gem) itself, library installation and compilation. (Feature tests for C++ unittest/arduino code belong in `../TestSomething/test/`.) ## Naming convention -Files in this directory are expected to have names that either contains "bad" if it is expected to fail or "good" if it is expected to pass. This provides a signal to `rspec` for how the code is expected to perform. +Files in this directory are given names that either contains "bad" (if it is expected to fail) or "good" (if it is expected to pass). This provides a signal to `rspec` for how the code is expected to perform (see `spec/cpp_library_spec.rb`). + +When writing your own tests you should not follow this ("bad" and "good") naming convention. You should write all your tests expecting them to pass (relying on this `DoSomething` test to ensure that failures are actually noticed!). diff --git a/SampleProjects/README.md b/SampleProjects/README.md index 8e4e3405..6b7ed569 100644 --- a/SampleProjects/README.md +++ b/SampleProjects/README.md @@ -1,7 +1,7 @@ Arduino Sample Projects ======================= -This directory contains example projects that are meant to be built with this gem. +This directory contains projects that are meant to be built with and tested by this gem. Although this directory is named `SampleProjects`, it is by no means optional. These project test the testing framework itself, but also provide examples of how you might write your own tests (which should be placed in your system's Arduino `libraries` directory). -* "DoSomething" is a bare implementation of a library with a test. Test files prefixed with "bad-" are expected to fail; this is checked as part of the testing on arduino_ci itself. -* "TestSomething" contains a minimial library, but tests for all the mock features of arduino_ci. +* "DoSomething" is a simple test of the testing framework (arduino_ci) itself to verfy that passes and failures are properly identified and reported. +* "TestSomething" contains tests for all the mock features of arduino_ci.