Appendix B. Submissions and Check-ins[LINK]
There are two methods by which new modules are entered into the EnergyPlus (publicly available) program.
-
Checkin: Part of the core development team may create or modify an existing module. As we use a configuration management system – this is called a check in.
Note — to save people grief and rework effort and to work toward consistency in approach, new features or changes to existing features must be proposed in a documented way for discussion during one of the bi-weekly conference calls.
-
Submission: When someone outside the core development team submits a module or modification of an existing module for inclusion, this is termed a submission.
Submissions are subjected to the same kind of scrutiny as team checkins and usually will require rework by the submitter. We welcome outside developers to send their ideas as early documents for comment with the understanding that revising does not guarantee automatic inclusion. See the proposed feature outline document in Appendix F and/or the “doc” file in the Documents for Developers Zip file.
Both kinds of inclusions need to follow the checklist procedure for new inclusions:
ü Source Code Rules
Shall follow programming standard
Shall follow F90/95 or later standards (use “allocatable” for allocatable structures within Derived Types)
Shall follow the Template standards (documentation, naming conventions)
Shall follow the guidelines shown in this document
All items shall be directly initialized (exception: derived type elements may be staticly initialized)
There shall be no “unused” variables. If you put in a variable that you “might use later” – comment it out and comment it to be used later.
No Tabs in source code!!!
Lines shall be less than 133 characters in length. (Some compilers allow longer lines without warning).
Suggest using F95 standards checking during compiles – you may use the compiler option to generate warnings for non-standard code.
Permission to use the code shall be supplied – written, even email, is required. LBNL is monitoring this aspect – so a grant-back letter can also be obtained from them.
ü Energy+.IDD rules
Standard Units shall be used (SI only on Input)
Show units with the \units field. Supply \ip-units only if your input would require it (see comments at top of the Energy+.idd).
Use \minimum and \maximum
The first field following the object name should contain “name” as part of the field name
Use \default, \min-fields and \required-field appropriately
Object changes during minor releases (x.x.xxx) should not change fields in the middle – only at the end
Surface objects may not add further fields to the end (the end is reserved for vertices and extension to the current limits)
Note that changes in the Energy+.idd will require a “transition” rule change in the Rules Spreadsheet file (Rules…xls). Likewise, changes in report variable names must be documented in the “report variables” change file that is a companion to the Rules spreadsheet.
ü Testing
Shall run the full test suite for all new features and unless you are absolutely, positively sure that your change will not impact other parts of the code. We have a python script that can compare between two run versions (using the .csv files output from ReadVarsESO).
If you need a script, look under StarTeam…Test Files>ScriptMaker. Other scripts are mentioned in the section on “Running EnergyPlus for Developers” (Module Developer’s Guide).
If you modify objects, you must change all test suite files that are impacted by your object modifications.
ü New Features need a new example file
You must create a new input file for your changes—input files shall include appropriate internal documentation! (Test files have a document template as well seeAppendix E. Test File Documentation). Some features may be appropriately added to an existing file but documentation must be updated.
You must fill out a line in the “ExampleFiles.xls” spreadsheet for your new input file.
You must run a full annual run with your test file even if that is not the configuration that ends up in the internal test suite. Annual runs have been known to fail – obviously, your input file should not.
You must try to minimize the number of errors shown in the eplusout.err file for your files.
Reverse DD Compliance Test: You must run a test that reverses a run of two environments (design days) and make sure that the results (when you also reverse the results files) are identical. (Identical means exactly the same.) Several scripts and automated programs to accomplish this feat are available.
ü Documentation (must be included at the same time as code!!!)
A document template is available for use – only the styles in that document should be used. (MicrosoftTM Word is our standard word processing software).
Equations – limited in IORef, necessary in Engineering Doc – limit the number of “references” though. You can use standard Equation formatting from MicrosoftTM Word or MathtypeTM is an acceptable alternate.
Figures – Though AutoShapes may draw nice pictures, they are not often “captionable” without undue editing. Please make figures into Jpegs or GIFs. Use “insert caption” (below the figure) so that auto-numbering of figures is used (these will transfer automatically to EnergyPlus documents).
Tables – use “insert caption” (above the table) so that auto-numbering of figures is used (these will transfer automatically to EnergyPlus documents).
Cross-References – limit your “insert cross references”. You should highlight these so that “editing” from your inclusion is more obvious – use a different color to help them stand out.
IORef – See the InputOutputReference document for indications of what is included.
Eng Ref – New modules shall include an engineering document reference. See the Engineering Reference for indications of typical writeups.
Output Details and Examples – this can help illustrate your changes. Any new files must be detailed in here. Likewise, changes to the .eio file must be described.
ü FeatureChanges.csv
Every change to source code, example files, datsets, utilities (any change other than documentation) must include a line in the “featurechanges.csv” file.
ü Checked in?
A courtesy message to the EnergyPlus team should be done for each check in, with details of files checked in, etc. Save one of the emails you have received if you don’t know how many to send it to.
ü Defect fixing?
If you fix a defect or “fix” a suggested change (CR), you should mark it “fixed” in StarTeam and the responsibility should automatically change back to the author of the CR. If you fix your own CR, assign it to someone else for verification.
If you fix a defect or “fix” a suggested change, you should provide a “synopsis for users” (on the “Custom” tab in the CR edit dialog) so that when we release the version with your fix, we can provide something descriptive for the users.
If a defect has a workaround, you should enter this in the “Workaround” field (on the “Solution” tab) to inform users until the fix is released in a public version.
ü Rules…xls
If a transition rule will be needed (or a deleted / obsolete / renamed object is needed) – a line (or more) in this spreadsheet must be used. See example rules files from previous releases. If in doubt, put something in.
ü ReportVariables…csv
If you change the name of a report variable, the transition program for release can automatically transition older input files IF you put the old and new names into this file.
If you delete a report variable, that detail should go in this file. Note that you must consult others on the core development team before deleting a reported variable.
Appendix B. Submissions and Check-ins[LINK]
There are two methods by which new modules are entered into the EnergyPlus (publicly available) program.
Note — to save people grief and rework effort and to work toward consistency in approach, new features or changes to existing features must be proposed in a documented way for discussion during one of the bi-weekly conference calls.
Submissions are subjected to the same kind of scrutiny as team checkins and usually will require rework by the submitter. We welcome outside developers to send their ideas as early documents for comment with the understanding that revising does not guarantee automatic inclusion. See the proposed feature outline document in Appendix F and/or the “doc” file in the Documents for Developers Zip file.
Both kinds of inclusions need to follow the checklist procedure for new inclusions:
ü Source Code Rules
Shall follow programming standard
Shall follow F90/95 or later standards (use “allocatable” for allocatable structures within Derived Types)
Shall follow the Template standards (documentation, naming conventions)
Shall follow the guidelines shown in this document
All items shall be directly initialized (exception: derived type elements may be staticly initialized)
There shall be no “unused” variables. If you put in a variable that you “might use later” – comment it out and comment it to be used later.
No Tabs in source code!!!
Lines shall be less than 133 characters in length. (Some compilers allow longer lines without warning).
Suggest using F95 standards checking during compiles – you may use the compiler option to generate warnings for non-standard code.
Permission to use the code shall be supplied – written, even email, is required. LBNL is monitoring this aspect – so a grant-back letter can also be obtained from them.
ü Energy+.IDD rules
Standard Units shall be used (SI only on Input)
Show units with the \units field. Supply \ip-units only if your input would require it (see comments at top of the Energy+.idd).
Use \minimum and \maximum
The first field following the object name should contain “name” as part of the field name
Use \default, \min-fields and \required-field appropriately
Object changes during minor releases (x.x.xxx) should not change fields in the middle – only at the end
Surface objects may not add further fields to the end (the end is reserved for vertices and extension to the current limits)
Note that changes in the Energy+.idd will require a “transition” rule change in the Rules Spreadsheet file (Rules…xls). Likewise, changes in report variable names must be documented in the “report variables” change file that is a companion to the Rules spreadsheet.
ü Testing
Shall run the full test suite for all new features and unless you are absolutely, positively sure that your change will not impact other parts of the code. We have a python script that can compare between two run versions (using the .csv files output from ReadVarsESO).
If you need a script, look under StarTeam…Test Files>ScriptMaker. Other scripts are mentioned in the section on “Running EnergyPlus for Developers” (Module Developer’s Guide).
If you modify objects, you must change all test suite files that are impacted by your object modifications.
ü New Features need a new example file
You must create a new input file for your changes—input files shall include appropriate internal documentation! (Test files have a document template as well seeAppendix E. Test File Documentation). Some features may be appropriately added to an existing file but documentation must be updated.
You must fill out a line in the “ExampleFiles.xls” spreadsheet for your new input file.
You must run a full annual run with your test file even if that is not the configuration that ends up in the internal test suite. Annual runs have been known to fail – obviously, your input file should not.
You must try to minimize the number of errors shown in the eplusout.err file for your files.
Reverse DD Compliance Test: You must run a test that reverses a run of two environments (design days) and make sure that the results (when you also reverse the results files) are identical. (Identical means exactly the same.) Several scripts and automated programs to accomplish this feat are available.
ü Documentation (must be included at the same time as code!!!)
A document template is available for use – only the styles in that document should be used. (MicrosoftTM Word is our standard word processing software).
Equations – limited in IORef, necessary in Engineering Doc – limit the number of “references” though. You can use standard Equation formatting from MicrosoftTM Word or MathtypeTM is an acceptable alternate.
Figures – Though AutoShapes may draw nice pictures, they are not often “captionable” without undue editing. Please make figures into Jpegs or GIFs. Use “insert caption” (below the figure) so that auto-numbering of figures is used (these will transfer automatically to EnergyPlus documents).
Tables – use “insert caption” (above the table) so that auto-numbering of figures is used (these will transfer automatically to EnergyPlus documents).
Cross-References – limit your “insert cross references”. You should highlight these so that “editing” from your inclusion is more obvious – use a different color to help them stand out.
IORef – See the InputOutputReference document for indications of what is included.
Eng Ref – New modules shall include an engineering document reference. See the Engineering Reference for indications of typical writeups.
Output Details and Examples – this can help illustrate your changes. Any new files must be detailed in here. Likewise, changes to the .eio file must be described.
ü FeatureChanges.csv
Every change to source code, example files, datsets, utilities (any change other than documentation) must include a line in the “featurechanges.csv” file.
ü Checked in?
A courtesy message to the EnergyPlus team should be done for each check in, with details of files checked in, etc. Save one of the emails you have received if you don’t know how many to send it to.
ü Defect fixing?
If you fix a defect or “fix” a suggested change (CR), you should mark it “fixed” in StarTeam and the responsibility should automatically change back to the author of the CR. If you fix your own CR, assign it to someone else for verification.
If you fix a defect or “fix” a suggested change, you should provide a “synopsis for users” (on the “Custom” tab in the CR edit dialog) so that when we release the version with your fix, we can provide something descriptive for the users.
If a defect has a workaround, you should enter this in the “Workaround” field (on the “Solution” tab) to inform users until the fix is released in a public version.
ü Rules…xls
If a transition rule will be needed (or a deleted / obsolete / renamed object is needed) – a line (or more) in this spreadsheet must be used. See example rules files from previous releases. If in doubt, put something in.
ü ReportVariables…csv
If you change the name of a report variable, the transition program for release can automatically transition older input files IF you put the old and new names into this file.
If you delete a report variable, that detail should go in this file. Note that you must consult others on the core development team before deleting a reported variable.
Documentation content copyright © 1996-2020 The Board of Trustees of the University of Illinois and the Regents of the University of California through the Ernest Orlando Lawrence Berkeley National Laboratory. All rights reserved. EnergyPlus is a trademark of the US Department of Energy.
This documentation is made available under the EnergyPlus Open Source License v1.0.