From cac77e5ffa256443355e4a83df4988dcd6629712 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emil=20Sj=C3=B6lander?= Date: Tue, 13 Feb 2018 07:06:31 -0800 Subject: [PATCH] Add contributing docs Reviewed By: danielbuechele Differential Revision: D6976258 fbshipit-source-id: 71b3d0ab4a071ce0c4a9c1241cd6295aa6d52b8e --- .../contents/contributing/adding-a-test.md | 7 --- .../contributing/checking-out-the-code.md | 7 --- .../contents/contributing/making-a-change.md | 7 --- .../contributing/opening-a-pull-request.md | 50 ++++++++++++++++++- .../contributing/running-the-test-suite.md | 7 --- website/contents/contributing/testing.md | 45 +++++++++++++++++ 6 files changed, 94 insertions(+), 29 deletions(-) delete mode 100644 website/contents/contributing/adding-a-test.md delete mode 100644 website/contents/contributing/checking-out-the-code.md delete mode 100644 website/contents/contributing/making-a-change.md delete mode 100644 website/contents/contributing/running-the-test-suite.md create mode 100644 website/contents/contributing/testing.md diff --git a/website/contents/contributing/adding-a-test.md b/website/contents/contributing/adding-a-test.md deleted file mode 100644 index e740bbbb..00000000 --- a/website/contents/contributing/adding-a-test.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -path: "contributing/adding-a-test" -title: "Adding a Test" -hasPlayground: false ---- - -## Adding a Test diff --git a/website/contents/contributing/checking-out-the-code.md b/website/contents/contributing/checking-out-the-code.md deleted file mode 100644 index 21c7d9bc..00000000 --- a/website/contents/contributing/checking-out-the-code.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -path: "contributing/checking-out-the-code" -title: "Checking Out the Code" -hasPlayground: false ---- - -## Checking Out the Code diff --git a/website/contents/contributing/making-a-change.md b/website/contents/contributing/making-a-change.md deleted file mode 100644 index 7b44c023..00000000 --- a/website/contents/contributing/making-a-change.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -path: "contributing/making-a-change" -title: "Making a change" -hasPlayground: false ---- - -## Making a change diff --git a/website/contents/contributing/opening-a-pull-request.md b/website/contents/contributing/opening-a-pull-request.md index 9cdc5c81..aaf232e4 100644 --- a/website/contents/contributing/opening-a-pull-request.md +++ b/website/contents/contributing/opening-a-pull-request.md @@ -4,4 +4,52 @@ title: "Opening a Pull Request" hasPlayground: false --- -## Opening a Pull Request +# Opening a Pull Request + +Before opening your first pull request to Yoga you have to know how to get the code, +install build time dependencies, and test the code locally. + +### Clone + +``` +$> git clone https://github.com/facebook/yoga.git +$> cd yoga +``` + +### Install dependencies + +``` +$> git submodule init +$> git submodule update +$> brew install buck +``` + +### Build and Test + +``` +$> buck build //:yoga +$> buck test //:yoga +``` + +## Making a Change + +Now all you need to do is make your change and test it before submitting a pull request for review. +Below is the general structure of the repo and where you may want to make your change. One you have +made your change see the [testing documentation](/contributing/testing) for more on how to test your change. + +``` bash +/yoga +|-- yoga # Home to the main Yoga codebase written in C++. Any algorithmic changes should be made here +|-- lib # Yoga external dependencies. Be thoughtful adding any new ones +|-- tests # Yoga's C++ test suite. Both manaul and generated tests +|-- gentest +| |-- fixtures # html fixtures for generated tests +|-- java +| |-- com/facebook/yoga # Java binding code +| |-- jni # JNI binding code +|-- yogacore # Android bindings without View support +|-- android # Android View bindings +|-- YogaKit # iOS UIView bindings +|-- javascript # emscripten / javascript bindings +|-- csharp # .NET bindings in c# +``` \ No newline at end of file diff --git a/website/contents/contributing/running-the-test-suite.md b/website/contents/contributing/running-the-test-suite.md deleted file mode 100644 index 6000341d..00000000 --- a/website/contents/contributing/running-the-test-suite.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -path: "contributing/running-the-test-suite" -title: "Running the Test Suite" -hasPlayground: false ---- - -## Running the Test Suite diff --git a/website/contents/contributing/testing.md b/website/contents/contributing/testing.md new file mode 100644 index 00000000..91f4ee30 --- /dev/null +++ b/website/contents/contributing/testing.md @@ -0,0 +1,45 @@ +--- +path: "contributing/testing" +title: "Testing" +hasPlayground: false +--- + +# Testing + +Yoga tries to be as close as possible to chrome in its flexbox behaviour. +To ensure this most of Yoga's test suite is automatically generateded from +running the corresponding layout in chrome using a webdriver which then generates +C++ test which asserts that Yoga will produce matching outputs for that layout. + +## Running the Test Suite + +1. Yoga builds with [buck](https://buckbuild.com). Follow their documentation to get up and running. +2. For testing Yoga relies on [gtest](https://github.com/google/googletest) as a submodule. After cloning Yoga run `git submodule init` followed by `git submodule update`. +3. In a terminal from the root of your Yoga checkout run `buck test //:yoga`. + +## Adding a Test + +Instead of manually writing a test which ensures parity with web implementations +of Flexbox we make use of a generated test suite. We use `gentest/gentest.rb` to +generate this test suite. Write the html which you want to verify in Yoga and put +it in the `gentest/fixtures` folder, such as the following. + +```html +
+
+
+``` + +Run `gentest/gentest.rb` to generate test code and re-run `buck test //:yoga` +to validate the behavior. One test case will be generated for every root `div` +in the input html with the string in the `id` corresponding to the test name. + +You may need to install the latest watir gem (`gem install watir`) and +[ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/) to +run `gentest/gentest.rb` Ruby script. + +## Manual test + +For some aspects of Yoga we cannot generate a test using the test generation +infrastructure described earlier. For these cases we manually write a test in +the `/tests` directory.