README.md
1# RStudio Theme Maintenance
2
3Most of the themes the RStudio IDE bundles are maintained by pulling the CSS versions of the themes from ACE and regenerating them using the `compile-themes.R` script in the `src/gwt/tools` folder. In general, changes should not be made to `.rstheme` files manually, as they will be overwritten each time that the themes are regenerated. To (re)generate themes:
4
51. Naviagate to `src/gwt/tools`
62. Run `./sync-ace-commits`
73. Run `Rscript compile-themes.R`
8
9## Manually Maintained Themes
10
11Some themes were contributed to the RStudio IDE as already created `.rstheme` files, and do not have an associated source `.css` file. The following is the current list of themes which need to be updated manually if any changes are required:
12
13* material.rstheme
14
15## Test Cases
16
17The tests cases validate that `tmTheme` files can be converted into Ace CSS and that the same Ace CSS can then be converted into `rstheme` files . The Ace CSS files are the expected output for the `tmTheme -> Ace CSS` conversion, and the input for the `Ace CSS -> rstheme` conversion.
18
19In addition, the test cases also:
20 * validate that invalid `tmTheme`s will produce an error and not an Ace CSS file.
21 * validate that files are installed to the global and local theme directories correctly.
22 * validate that themes will not be installed to folders which have restrictive permissions.
23 * validate that themes will be installed (or not installed) over existing `rsthemes` with the same name based on the options specified.
24 * validate that the IDE bundled themes exist and the API returns the correct information about them.
25
26The folder structure of the tests cases is described below:
27 * `src/cpp/tests/testthat`
28 * `regenerate-css.R` - script which regenerates expected results
29 * `test-themes.R` - the themes test cases
30 * `themes` - root folder for expected input and output
31 * `acecss` - expected output for `tmTheme -> Ace CSS` and input for `Ace CSS -> rsthemes`
32 * `errorthemes` - invalid `tmTheme` files that should generate an error
33 * `globalInstall` - folder that will be used as the "global" install location. Should be empty after tests complete.
34 * `localInstall` - folder that will be used as the "local" install location. Should be empty after tests complete.
35 * `nopermission` - folder with restrictive permissions. Should always be empty.
36 * `rsthemes` - expected output for `Ace CSS -> rstheme` conversion
37 * `thmThemes` - input for `tmTheme -> Ace CSS` conversion
38
39### Fixing the Test Cases
40
41The most common cause of failing test cases is that new fields were added to (or extra fields were removed from) the generated `rstheme` files. The expected results can be updated using the `regenerate-css.R` script by loading the `themes` list from `test-themes.R` into the local R environment and then sourcing `regenerate-css.R`. Note that `xml2` is required, as it would be to install a custom theme to the IDE. After regenerating the expected results, it is a good idea to manually check that the changes in the expected results are only include the changes you expected.
42
43Another easy-to-fix scenario is when a new bundled theme is added to the IDE. To resolve this, add a new line to the `defaultThemes` list in `test-themes.R` (in alphabetical order) for the new theme and set the `fileName` and `isDark` fields as appropriate.
44
45Other problems in the test cases may require debugging. The easiest way to debug the test cases is to add a `browser` call to the failing test case and then run `testthat::test_file("test-themes.R")` from the R console. Note that this requires the working directory of the R console to be `src/cpp/tests/testthat`. Alternately, a full or relative path to the `test-themes.R` file may be provided.
46
47NOTE: Changes to `src/cpp/session/modules/resources/compile-themes.R` and `src/cpp/session/modules/SessionThemes.R` require the CMake project to be reloaded before they will be observed in the test results.
48