Merge branch 'develop' into master for release 3.0

DLR-SL · Sep 19, 2018 · b3b7fde · b3b7fde
2 parents e39183c + 78c9a7a
commit b3b7fde
Show file tree

Hide file tree

Showing 24 changed files with 6,608 additions and 3,342 deletions.
diff --git a/development/README.md b/development/README.md
@@ -0,0 +1,19 @@
+# CPACS Documentation
+
+## Overview
+
+All files in this folder are supposed to describe in some detail the development process of CPACS.  This file serves as overview or context file.
+
+## Contributions
+Contributions to the CPACS developments are always welcome. You can contribute by posting or commenting issues, help in the decision making process by commenting developments and contributing with changes to the schema e.g. through pull requests. In case you use CPACS for data exchange within a project please check [here](project_developments.md) for a brief introduction on how the developments can be organized. Details on the common development process and handling of issues can be found [here](development.md)
+For contributions you can use the same steps as described in the "Development Process" section. 
+
+## Contents
+
+1. [Project developments](project_developments.md)
+2. [Development process](development.md)
+3. [Tools](tools.md)
+4. [Repository structure](repository.md)
+5. [Release process](release.md)
+6. [Known Issues](known_issues.md)
+
diff --git a/development/development.md b/development/development.md
@@ -0,0 +1,156 @@
+# CPACS Development
+
+## Organizing Branches
+The developments of CPACS follows the Gitflow workflow as described in [https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow "https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow"). For the developments there are two main branches. While the *master* branch is used for keeping track of the official releases, the *develop* branch is used to combine all the developments and thus contains the main development version. All Feature branches are merged into the *develop* branch.
+
+## Development Process
+
+The purpose of this text is to describe the way CPACS should be developed in between releases. To learn more about the actual release process please look up the corresponding file. 
+
+All developments concerning CPACS should be documented in a public issue tracker. Please note, that this is currently carried out on the github site after the move from googlecode. ~~Nevertheless, in the future one might move CPACS to a new home on the net and develop an integrated process, i.e. issue tracker and repository linked directly. ~~
+
+Some guidelines for the CPACS development process: 
+
+- Each issue should be marked with a target version. 
+- Before implementation, each issue should be checked for conflicts with other parts of the parametrization. 
+- No issue shall be implemented without documentation in the CPACS schema file!!!
+- Redundancy in the CPACS schema should be avoided by all means. 
+- If a multi-fidelity definition is requested than it should occur on different levels of the schema to prohibit redundancy, e.g. massBreakdown. 
+
+
+In general the inclusion of new items should work more or less in this order: 
+
+1. Open issue and specify targets
+2. Gather all "stakeholders" and start discussion process. In a best case, one of the stakeholders provides an initial proposal as a baseline for further discussions. 
+3. Note the state of the discussion in the issue file. 
+4. Prototype implementation in CPACS schema
+5. Final implementation including documentation
+6. Issue closed and feature marked for target version of CPACS
+
+
+Incoming issues from outside the development team should be checked before beeing accepted.
+The following questions should be answered:
+
+- What is the driver for the requested change.
+- If new definitions shall be implemented; Is there an immediate plan to exchange the data between different parties? Don't waste time on the definition of nodes which might not be used for data exchange.
+
+
+## Contribution Guidelines
+TODO
+
+
+## Development Guidelines
+We will try to find/define some guidelines for decisions on how to structure CPACS.
+
+First loose collection:
+
+- Always use SI and accepted derived units
+- Use the CPACS coordinate system for describing data (Do not introduce new coordinate systems if not absolutely neccessary)
+
+
+
+
+## Additional Development Guidelines by Example
+TODO: Explaining guidelines using examples from previous decisions...
+
+### Duplication VS Single Type Reference VS Hidden Changes
+Let us discuss different approaches at the example of introducing a second option for specifying internal wing points by using segment eta xsi coordinates.
+This related to issue https://github.com/DLR-LY/CPACS/issues/495.
+
+In principle I see three different possibilities to implement the two options.
+
+1. add an additional segmentUID node next to eta and xsi. THen, whenever a segmentUID is given the eta and xsi nodes should be interpreted as segment eta xsi coordinates.
+  ```
+  <parentNode>
+    <eta />
+    <xsi />
+    <segmentUID /> <!-- optional -->
+  </parentNode>
+```
+2. add the option as a choice between [eta, xsi] or [etaSeg, xsiSeg, segmentUID]
+  ```
+  <parentNode>
+    <!-- choice 1 start-->
+    <eta />
+    <xsi />
+    <!-- choice 1 end -->
+    <!-- choice 2 -->
+    <etaSeg />
+    <xsiSeg />
+    <segmentUID />
+    <!-- choice 2 end -->
+  </parentNode>
+```
+3. combine both options as described in 2. into their own parent node
+  ```
+  <parentNode>
+    <!-- choice 1 start-->
+    <componentSegmentPoint>
+      <eta />
+      <xsi />
+    </componentSegmentPoint>
+    <!-- choice 1 end -->
+    <!-- choice 2 -->
+    <segmentPoint>
+      <eta />
+      <xsi />
+      <segmentUID />
+    </segmentPoint>
+    <!-- choice 2 end -->
+  </parentNode>
+```
+
+Option 1. is clearly a very reduced approach. It allows the user of the data to switch the interpretation of the eta and xsi nodes depending on the existence of the segmentUID node. A risk of this approach is that without modifications, existing tools might miss the additional segmentUID node and thus misinterpret the point.
+Option 2. avoids misinterpreting the segment eta xsi values by giving them a different node name. But the drawback is the additional nodes (node names) which need to be processed.
+Option 3. is very similar to option 2. but keeps eta xsi as the names also for segment eta xsi coordinates and creates an additional intermediate node for both options. This opens up the opportunity to create separate types for both options which can be reused at several locations throughout the schema. This would minimize the effort in case changes are required for the definition of the points and ensures some consistency in the use of eta xsi points. E.g. if we had an etaXsiPointType for componentSegment points we could find all uses throughout the schema to implement the segment coordinate alternative. Also creating an additional type allows us to use xsd:all within the type definition which otherwise would not be possible due to the xsd:choice.
+
+
+### Favor compact solutions
+... if feasible
+
+For point clouds such as used in wing profiles in early CPACS versions a point definition with x,y and z coordinate was used for every profile point.
+
+```
+<points>
+  <point uID="p1">
+    <x>0.0</x>
+    <y>0.0</y>
+    <z>0.0</z>
+  </point>
+  <point uID="p2">
+    <x>1.0</x>
+    <y>0.0</y>
+    <z>0.0</z>
+  </point>
+  <point uID="p3">
+    <x>1.0</x>
+    <y>0.0</y>
+    <z>1.0</z>
+  </point>
+  <point uID="p4">
+    <x>0.0</x>
+    <y>0.0</y>
+    <z>1.0</z>
+  </point>
+  <point uID="p5">
+    <x>0.0</x>
+    <y>0.0</y>
+    <z>0.5</z>
+  </point>
+  <point uID="p6">
+    <x>0.0</x>
+    <y>0.0</y>
+    <z>0.0</z>
+  </point>
+</points>
+```
+
+In this case the overhead of data due to the tags was much higher than the actual data to be exchanged. Thus it was changed to a more compact definition:
+
+```
+<pointList>
+  <x>0.0;1.0;1.0;0.0;0.0;0.0</x>
+  <y>0.0;0.0;0.0;0.0;0.0;0.0</y>
+  <z>0.0;0.0;1.0;1.0;0.5;0.0</z>
+</pointList>
+```
diff --git a/development/development.txt b/development/development.txt
diff --git a/development/images/centralized.png b/development/images/centralized.png
diff --git a/development/known_issues.txt → development/known_issues.md b/development/known_issues.txt → development/known_issues.md
diff --git a/development/overview.txt b/development/overview.txt
diff --git a/development/project_developments.md b/development/project_developments.md
@@ -0,0 +1,19 @@
+# Developments in Research Projects
+Since the start of the developments in 2005, CPACS and its user community have grown constantly.
+By now CPACS is used in many different research projects. Each project has a different focus and thus individual requirements for using CPACS. In order not to hamper the project activities a separate development branch should be created for each project where the results from feature branches can be combined into a project specific CPACS version. For easier integration into the development branch of the official CPACS repository, changes should still be developed in feature branches which are kept until integration to the official CPACS has been performed. This allows to easier integrate features individually.
+The most common reasons for ongoing developments in CPACS are the following. 
+
+## Missing Data
+When CPACS is used in research projects you might find that you need to store additional data for which there is no definition in CPACS. In such a case we suggest the following approach:
+
+1. An immediate solution can be to use the toolspecific node for user specific data. This allows you to continue with the project without relying on a time consuming development process for modifying the schema, and through practical experiences and quick development cycles you should be able to identify the relevant data relatively fast. If this is all you need for your project you can stop here. But in case you would like to contribute to the development of CPACS you should continue with the next steps.
+
+2. The next step is to find a suitable node structure for the CPACS data and identify where the data should be located. This should be done by involving experts from all the participating disciplines as well as considering the main CPACS development guidelines. If more accessible the discussions can be done based on example XML files describing the structure rather than the XSD file. Once an agreement has been reached on the data structure you can follow with the next step.
+
+3. Modify the schema (XSD) file of CPACS according to your findings. Commit the changes small digestable pieces. By using separate commits for each semantic change, integration can be simplified a lot. Try and keep consistent with common practices in CPACS (an official collection of practices still has to be assembled). 
+
+4. Create a pull request as explained at [https://help.github.com/articles/creating-a-pull-request/](https://help.github.com/articles/creating-a-pull-request/ "Creating a Pull Request") and wait for feedback.
+
+
+## Unsuitable Data Structure
+If you discover that a data structure is not suitable for your task/project you can take the same approach as for missing data, but when finding a new structure try to reduce the required changes to a minimum. If this is not possible or this would not lead to a feasible result, you might aswell redesign the concerning CPACS nodes. In such a case the integration process to the main development branch is much more difficult sinca all parties which use the existing nodes should be allowed to make their case. This will trigger a discussion which need to be resolved within the CPACS community.
diff --git a/development/release.txt → development/release.md b/development/release.txt → development/release.md
@@ -22,4 +22,4 @@ The release process is grouped into the following steps:
 Currently, CPACS is supported by TIXI and TIGL as interfaces to CPACS. Additionally, there is the possibility to create bindings for other languages as well. This becomes especially handy once users try to generate CPACS files. Within the CPACS release schedule two binding will be generated: Python and Java. The Python bindings are created using the generateDS library; Java bindings via JAXB, see the tools section. Both calls are listed in the generateLibraries batch file. 
 
 ## 4. Upload files 
-tbd
+tbd
diff --git a/development/repository.txt → development/repository.md b/development/repository.txt → development/repository.md
diff --git a/development/tools.txt → development/tools.md b/development/tools.txt → development/tools.md
diff --git a/documentation/Cpacs_doc_project.shfbproj b/documentation/Cpacs_doc_project.shfbproj
@@ -45,7 +45,7 @@
     <MissingTags>Summary, Parameter, Returns, Remarks, AutoDocumentCtors, Namespace, TypeParameter</MissingTags>
     <CopyrightHref>
     </CopyrightHref>
-    <CopyrightText>%28c%29 2015 Deutsches Zentrum fuer Luft- und Raumfahrt e.V.</CopyrightText>
+    <CopyrightText>%28c%29 2018 Deutsches Zentrum fuer Luft- und Raumfahrt e.V.</CopyrightText>
     <FeedbackEMailAddress>jonas.jepsen%40dlr.de</FeedbackEMailAddress>
     <FeedbackEMailLinkText>
     </FeedbackEMailLinkText>
@@ -139,6 +139,14 @@
       <ImageId>engineNacelle</ImageId>
       <AlternateText>engine nacelle</AlternateText>
     </Image>
+    <Image Include="geometricBaseTypes.png">
+      <ImageId>geometricBaseTypes</ImageId>
+      <AlternateText>basic shapes of geometric base types</AlternateText>
+    </Image>
+    <Image Include="GuideCurveDocumentation.png">
+      <ImageId>guideCurveIllustration</ImageId>
+      <AlternateText>Illustration of guide curves</AlternateText>
+    </Image>
     <Image Include="guideProfileLong.JPG">
       <ImageId>guideProfileLong</ImageId>
       <AlternateText>guide Profile Long</AlternateText>
@@ -230,6 +238,18 @@
     <Image Include="wingcomponentsegments.jpg">
       <ImageId>wingcomponentsegments</ImageId>
       <AlternateText>wingcomponentsegments</AlternateText>
+    </Image>
+	<Image Include="componentsegments_1.png">
+      <ImageId>componentsegments_1</ImageId>
+      <AlternateText>componentsegments_1</AlternateText>
+    </Image>
+	<Image Include="componentsegments_2.png">
+      <ImageId>componentsegments_2</ImageId>
+      <AlternateText>componentsegments_2</AlternateText>
+    </Image>
+	<Image Include="componentsegments_3.png">
+      <ImageId>componentsegments_3</ImageId>
+      <AlternateText>componentsegments_3</AlternateText>
     </Image>
     <Image Include="tracks_ted.jpg">
       <ImageId>tracks_ted</ImageId>
@@ -271,13 +291,9 @@
       <ImageId>mlg</ImageId>
       <AlternateText>mlg</AlternateText>
     </Image>
-    <Image Include="etaxsi2.jpg">
-      <ImageId>etaxsi2</ImageId>
-      <AlternateText>etaxsi 2</AlternateText>
-    </Image>
-    <Image Include="etaxsi1.jpg">
-      <ImageId>etaxsi1</ImageId>
-      <AlternateText>etaxsi 1</AlternateText>
+    <Image Include="wingExplicitStringer.jpg">
+      <ImageId>wingexplicitstringer</ImageId>
+      <AlternateText>explicit wing stringer</AlternateText>
     </Image>
     <Image Include="wingstringer.jpg">
       <ImageId>wingstringer</ImageId>
@@ -316,4 +332,4 @@
   </ItemGroup>
   <!-- Import the SHFB build targets -->
   <Import Project="$(SHFBROOT)\SandcastleHelpFileBuilder.targets" />
-</Project>
+</Project>
diff --git a/documentation/GuideCurveDocumentation.pdf b/documentation/GuideCurveDocumentation.pdf
diff --git a/documentation/GuideCurveDocumentation.png b/documentation/GuideCurveDocumentation.png
diff --git a/documentation/componentSegments_1.png b/documentation/componentSegments_1.png
diff --git a/documentation/componentSegments_2.png b/documentation/componentSegments_2.png
diff --git a/documentation/componentSegments_3.png b/documentation/componentSegments_3.png
diff --git a/documentation/etaxsi1.jpg b/documentation/etaxsi1.jpg
diff --git a/documentation/etaxsi2.jpg b/documentation/etaxsi2.jpg
diff --git a/documentation/geometricBaseTypes.png b/documentation/geometricBaseTypes.png
diff --git a/documentation/wingExplicitStringer.jpg b/documentation/wingExplicitStringer.jpg