README.md in openstudio-extension-0.4.4 vs README.md in openstudio-extension-0.5.0
- old
+ new
@@ -8,14 +8,14 @@
Derivative extension gems should include this gem to access common functionality, such as:
* OpenStudio CLI functionality such as list_measures and update_measures
* adding documentation and license files to measures
* adding core resource files to measures
-* pushing measures to BCL
+* correct structure for contributing content to the Building Component Library (BCL)
Extension gems will contain a small group of related measures. Each extension gem will be the unique location to find these measures, and will be responsible for
-testing and maintaining the measures as well as pushing them to BCL.
+testing and maintaining the measures as well as indexing them on BCL.
## Usage
The ```openstudio-extension``` gem is meant to be used as a base for creating new gems to use with OpenStudio. The intention is to standardize best practices and common patterns in one location rather than try to synchronize them across many independent gems.
@@ -29,11 +29,11 @@
| module OpenStudio module ModelArticulation class ModelArticulation < OpenStudio::Extension::Extension | module BuildingSync class BuildingSync < OpenStudio::Extension::Extension |
## Installation
-To use the latest version of this and other extension gems, you will need Ruby 2.7.x and OpenStudio 3.1.0 or greater.
+To use the latest version of this and other extension gems, you will need Ruby 2.7.x and OpenStudio 3.1.0 or greater. For earlier versions, view the [compatibility matrix](#compatibility-matrix) below.
### Windows Installation
Install Ruby with Devkit using the [RubyInstaller](https://rubyinstaller.org/downloads/archives/) for [Ruby 2.7.2 (x64)](
https://github.com/oneclick/rubyinstaller2/releases/download/RubyInstaller-2.7.2-1/rubyinstaller-devkit-2.7.2-1-x64.exe).
@@ -79,12 +79,20 @@
Add the RUBYLIB environment variable to your `bash_profile` (or similar) file. It should point to the Ruby folder within
the OpenStudio Application you just downloaded (replace 3.1.0 with the version you are using):
```
export RUBYLIB=/Applications/OpenStudio-3.1.0/Ruby
```
+## Compatibility Matrix
+|OpenStudio Extension Gem|OpenStudio|Ruby|
+|:--------------:|:----------:|:--------:|
+| 0.4.0 - 0.4.4 | 3.2 | 2.7 |
+| 0.3.0 - 0.3.2 | 3.1 | 2.5 |
+| 0.2.0 - 0.2.6 | 3.0 | 2.5 |
+| 0.1.6 and below | 2.9 and below | 2.2.4 |
+
## Contents
The OpenStudio Extension Gem (this repo) contains methods that can be shared across and extended by other derivative extension gems.
### Directory Structure
@@ -137,22 +145,19 @@
Note that this folder is for 'core' functionality; if a measure's requires a new one-off function, this should be developed in place, within the measure's `resources` folder.
Having a single repository for all measures, such as the OpenStudio-measures repo, can be cumbersome to test and keep up to date.
In this new framework, each extension gem will contain one or more related measures. The gem will be the new 'home' of these measures, and the repo owner will be responsible for testing and keeping the measures up to date.
-In the short term, in order to preserve the PAT/OS App functionality, resource files will still be copied directly into the measures, and these measures will be pushed to BCL.
+In the short term, in order to preserve the PAT/OS App functionality, resource files will still be copied directly into the measures, and these measures will be indexed on the BCL.
### Rake Tasks
Common Rake Tasks that are available to derivative extension gems include:
| Rake Task | Description |
| --------- | ----------- |
-| openstudio:bcl:test_login | Test BCL login |
| openstudio:bcl:search_measures | Search BCL |
-| openstudio:bcl:stage[reset] | Copy the measures/components to a staging location |
-| openstudio:bcl:push | Upload measures from the staging location |
| openstudio:change_log[start_date,end_date,apikey] | Print the change log from GitHub. Specify dates in yyyy-mm-dd format |
| openstudio:list_measures | List all measures in the calling gem |
| openstudio:measures:add_license | Add License File to measures in the calling gem |
| openstudio:measures:add_readme | Add README.md.erb file if it and the README markdown file do not already exist for a measure |
| openstudio:measures:copy_resources | Copy the resources files to individual measures in the calling gem |
@@ -208,17 +213,13 @@
* Use lowercase snake_case for methods and variables.
* Use CamelCase for classes and modules. (Keep acronyms like HTTP, RFC, XML uppercase.)
* All files and classes should have underscores (no dashes) and (lowercase snake_case)
* Dashes should be used in module names
-### Pushing to BCL
-Use the rake tasks listed above to stage and push measures to BCL.
-**Note of warning**: Use caution when pushing to the BCL. Public and private measures could be pushed to BCL from within an extension gem, even though the extension gem repo may be private.
+### Contributing measures to the BCL
+Register your extension gem repo with the [BCL Manifest](https://github.com/BuildingComponentLibrary/bcl-manifest) and [follow the instructions](https://github.com/BuildingComponentLibrary/bcl-manifest#contribute-content) to contribute content to the BCL.
-TODO: Add warning to rake task and lists what gems will be pushed
-TODO: Check that license files, etc. are present in each measure before pushing to BCL
-
## Include in a project
Add this line to your application's Gemfile:
```ruby
@@ -231,9 +232,13 @@
$ bundle update
Or install it yourself as:
$ gem install 'openstudio-extension'
+
+# Contributing
+
+Please review the [OpenStudio Contribution Policy](https://openstudio.net/openstudio-contribution-policy) if you would like to contribute code to this gem.
# Releasing the gem
* Update CHANGELOG.md
* Run `rake rubocop:auto_correct`