proposal to resolve Issue #31

.gitignore

 **/*~
 build/
 Framework/Particles/GeneratedParticleProperties.inc
+flymd.html
+flymd.md

COLLABORATION_AGREEMENT.md

 # Collaboration agreement
 
-The CORSIKA project very much welcomes all collaboration and contributions. The aim of the CORSIKA project is to create a scientific software framework as a fundamental tool for research. The collaboration agreement and the licinsing model are based on the guidelines layed out by HSF [[1]](https://hepsoftwarefoundation.org/activities/licensing.html) or CERN [[2]](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&ved=2ahUKEwiLqKG00dXdAhUOZFAKHdIwAh4QFjAAegQIARAC&url=https%3A%2F%2Findico.cern.ch%2Fcategory%2F4251%2Fattachments%2F101%2F505%2FOSL-2012-01-Open_Source_Licences_at_CERN-Short_version.pdf&usg=AOvVaw1n4S0PQCSeE6wbdfdhKDqF), [[3]](http://legal.web.cern.ch/licensing/software), and follow the examples of other big scientific software projects. 
+The CORSIKA project very much welcomes all collaboration and
+contributions. The aim of the CORSIKA project is to create a
+scientific software framework as a fundamental tool for research. The
+collaboration agreement and the licensing model are based on the
+guidelines layed out by HSF
+[[1]](https://hepsoftwarefoundation.org/activities/licensing.html) or
+CERN
+[[2]](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&ved=2ahUKEwiLqKG00dXdAhUOZFAKHdIwAh4QFjAAegQIARAC&url=https%3A%2F%2Findico.cern.ch%2Fcategory%2F4251%2Fattachments%2F101%2F505%2FOSL-2012-01-Open_Source_Licences_at_CERN-Short_version.pdf&usg=AOvVaw1n4S0PQCSeE6wbdfdhKDqF),
+[[3]](http://legal.web.cern.ch/licensing/software), and follow the
+examples of other big scientific software projects.
 
-The CORSIKA project consists of the contributions from the scientific community and individulas in a best effort to deliver the best possible computing performance and physics output. 
+The CORSIKA project consists of the contributions from the scientific
+community and individuals in a best effort to deliver the best
+possible computing performance and physics output. All possible
+liability and licensing question are strictly handled by the adopted
+software license.
 
 ## The software license of the CORSIKA project
-The license adopted for the CORSIKA project is the explicit copyleft licencse GPLv3, as copyied in full in the file [LICENSE](LICENSE). Each source file of the CORSIKA project contains a short statement of the copyright and this license. The code, documentation and content in the folder [ThirdParty](ThirdParty) is not integral part of the CORSIKA project and can be based on or include other licences. Check the content of this folder for details. It depends on the configuration of the build system to what extend this code is used to build CORSIKA. 
+The license adopted for the CORSIKA project is the explicit copyleft
+license GPLv3, as copied in full in the file
+[LICENSE](LICENSE). Each source file of the CORSIKA project contains a
+short statement of the copyright and this license. Each binary or
+source code release of CORSIKA must contain the file LICENSE. The
+code, documentation and content in the folder [ThirdParty](ThirdParty)
+is not integral part of the CORSIKA project and can be based on or
+include other licenses, which must be compatible with GPLv3. Check the
+content of this folder for details. It depends on the configuration of
+the build system to what extend this code is used to build CORSIKA.
 
-## Definition of coyright holder
-For legal reasons and the ability to maintin the CORSIKA project effectively over a very long lifespan of several decades, all contibuters are required to transfer their copyright to the CORSIKA project. Of course you will be duly credited and your name will appear on the contributors page and in the [AUTHORS](AUTHORS) file shipped with every binary and source distribution. The copyright transfer is necessary for us to be able to effectively defend the project in case of litigation. The copyright holder can change with time, which is decided by the "CORSIKA board". The current copyright holder is the "CORSIKA board", contact address: ralf.ulrich@kit.edu. 
+## Who is the "copyright holder"
+For legal reasons and the ability to maintain the CORSIKA project
+effectively over a very long lifespan of several decades, all
+contributors are required to transfer their copyright to the CORSIKA
+Project. Of course you will be duly credited and your name will appear
+on the contributors page and in the [AUTHORS](AUTHORS) file shipped
+with every binary and source distribution. The copyright transfer is
+necessary to be able to effectively defend the project in case of
+litigation. The copyright holder may change, if decided by the CORSIKA
+Project. The current copyright holder is the CORSIKA Project
+corsika-project@lists.kit.edu, with the current chair person Ralf Ulrich (KIT) ralf.ulrich@kit.edu.
 
-## Definition of a contributor, and software author
-All contributors will be co-listed as software authors of the CORSIKA project, and listed indefinitely in the [AUTHORS](AUTHORS) file. Contributors should add their name and contact data to the [AUTHORS](AUTHORS) file. 
+## Definition of a "contributor"
+Contributor is a person of whom at least one merge request was
+accepted for the master branch of the CORSIKA project at
+[https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika).
+All contributors will be co-listed and credited as (software) authors
+of the CORSIKA project, as well as listed indefinitely in the
+[AUTHORS](AUTHORS) file. Contributors should add their name and
+contact data to the [AUTHORS](AUTHORS) file, as part of one of their
+merge requests. This file is always distributed together with all
+source and binary releases.  If you contribute to any non-master
+branch, you can add your name to the [AUTHORS](AUTHORS) file of this
+particular branch, but all official releases are normally performed
+via the master branch.
 
-## Definition of a scientific author
-The scientific authors of the CORSIKA project must be named in any scientific context, for example in talks, proceedings, posters, journal paper or any other publication or outreach document. Scientific authors or contributors are listed in [SCIENTIFIC_AUTHORS](SCIENTIFIC_AUTHORS). Individuals are only listed as scientific authors if the Collaboration board decides, and any such decision can be revisited or revoked at any time by the CORSIKA board. The list of scientific authors change with time, reflecting the active group of individuals that actually contribute to a specific state of the CORSIKA project. For specific scientific publications, the list of scientific authors can also be extended beyond SCIENTIFIC_AUTHORS by the CORSIKA board, for example to highlight important input on physics, technology or modelling. 
+If you want to contribute, you need to read
+[GUIDELINES](GUIDELINES.md) and comply with these rules, or help to
+improve them.
 
-## Definition and working mode of the CORSIKA board
-The CORSIKA board consists of individuls who have ..... 
+## Definition and role of a "scientific author"
+The scientific authors of the CORSIKA project must be credited in any
+scientific context, for example in talks, proceedings, posters,
+journal paper or any other publication or outreach
+document. Scientific authors or contributors are listed in
+[SCIENTIFIC\_AUTHORS](SCIENTIFIC\_AUTHORS). Credit can be given by
+listing the names explicitly, or by referring to the
+SCIENTIFIC\_AUTHORS file of a specific CORSIKA release, or to a
+standard published CORSIKA reference in a refereed
+journal. Individuals are only included as scientific authors if the
+CORSIKA Projects agrees on it, and any such decision can be revisited,
+changed or revoked at any time by the CORSIKA Project. The list of
+scientific authors will change with time, reflecting the active group
+of individuals that actually contribute to a specific state/release of
+the CORSIKA project. For specific scientific publications, the list of
+scientific authors can also be extended beyond SCIENTIFIC\_AUTHORS by
+the CORSIKA Project, for example to highlight additional important
+input on physics, technology or modelling.
+
+## Definition and working mode of the CORSIKA Project panel
+The CORSIKA Project panel makes all decisions for the CORSIKA
+Project. It can also change the
+[COLLABORATION\_AGREEMENT](COLLABORATION\_AGREEMENT.md), the
+[GUIDELINES](GUIDELINES.md) or any other structure or document relevant for the CORSIKA Project.
+
+The CORSIKA Project *panel* consists (October 2018) of
+   
+  * Ralph Engel (KIT)
+  * Dieter Heck (KIT)
+  * Tanguy Pierog (KIT)
+  * Maximilian Reininghaus (KIT)
+  * Markus Roth (KIT)
+  * Ralf Ulrich (KIT)
+  * Michael Unger (KIT)
+  * Darko Veberic (KIT)
+  
+and can be contacted via corsika-project@lists.kit.edu.  The chair
+person of the CORSIKA Project is Ralf Ulrich (KIT). Members of the
+CORSIKA Project *panel* are *Maintainer* of the CORSIKA Project in
+gitlab at
+[https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika),
+and have special responsibilities for this reason. 
 
 ## Accepting new contributors, and authors
-The CORSIKA board can accept new scientific authors to be added to  [SCIENTIFIC_AUTHORS](SCIENTIFIC_AUTHORS), or remove them from there. Agreement to be scientific author can be linked to a temporary task or assignment. Not compliance with the GUIDELINES, or inactivity are reasons to be removed from the list.  
+The CORSIKA Project can accept new scientific authors to be added to
+[SCIENTIFIC\_AUTHORS](SCIENTIFIC\_AUTHORS), or remove them from
+there. Agreement to be scientific author can be linked to a temporary
+task or assignment. Not compliance with the
+[GUIDELINES](GUIDELINES.md), or inactivity, are reasons to be removed
+from the list.
+
+## Changing to a different license, for parts, or the complete project
+The CORSIKA Project can change the license for parts or the entire project. 
+
+## Planning and performing releases
+
+The CORSIKA Project decides on releases of the software, and about the content of it. 
 
-## Changing to a different license, for parts or the complete project
-The CORSIKA board can change the license for parts or the entire project.  
+## Changes to the Collaboration Agreement
 
-## Deciding and planning releases
-The CORSIKA board decides on any change to the Collaboration agreement, about design choices, as well as all software releases and scientific publications. 
+The CORSIKA Project decides on changes to the Collaboration
+agreement.

GUIDELINES

-nothign

GUIDELINES.md

+# Guidelines for code development, structure, formating etc.
+
+The CORSIKA Project very much welcomes contributions. Here we outlined
+how you can find the right place to contribute, and how to do that.
+Connect to http://gitlab.ikp.kit.edu and corsika-devel@lists.kit.edu
+or corsika-project@lists.kit.edu to get in touch with the project.
+The CORSIKA Project decides on the [GUIDELINES](GUIDELINES.md), and can
+change them.
+
+## Code formatting
+
+We rely on `clang-format` for code formatting. This has the tremendous
+advantage that definitely all code follows the same formatting rules,
+and nobody at any point needs to invest time and effort into code
+formatting. We provide a script `do-clang-format.sh`, which can be
+very useful. But we urge everybody to integrate `clang-format` already
+on the level of your source code editor. See [the official
+page](https://clang.llvm.org/docs/ClangFormat.html) for information
+about `clang-format` and its editor integration. 
+
+The definition of source code format is written down in the file
+[.clang-format](.clang-format) and can be changed, if the CORSIKA
+Project agrees on it. To see what is possible, check
+e.g. [link1](https://clangformat.com/) or
+[link2](https://zed0.co.uk/clang-format-configurator/).
+
+## Naming conventions
+
+While `clang-format` does the structural formatting, we still need to agree on naming conventions:
+
+  - Classes and structs start with capital letters
+  - Class member variables start with "f"
+  - Any static variable has a "g" prefix. A static member variable starts with "fg"
+  - Class member functions start with capital letters
+  - Any class getter begins with "Get", and setter with "Set"
+  - enums should be "enum class", and start with a capital "E", enum entries start with "e"
+
+  - We use namespaces to avoid clashes and to structure code
+    - *Everything* is part of the corsika namespace
+    - All classes and objects are encapsulated into suited sub-namespaces,
+      thus corsika::geometry, corsika::processes, corsika::units, etc.
+    - Namespace names do not use capital letters.  
+    - Every header file is copied during build and install into
+      "include/corsika/[namespace]" which also means, each header file
+      can only provide definitions for a _single_ namespace. It is one
+      main purpose of namespaces to structure the location of header
+      files.
+    - Each header file uses an include protection that includes at
+      least the namespace name, and header file name, thus, `#ifndef
+      __include_geometry_Point_h__` or `#ifnedf __geometry_Point_h__`,
+      or similar are acceptable.
+    - Header files should always be included with `<..>`, thus,
+      `#include <corsika/geometry/Point.h>` since the build system
+      will always provide the correct include directives (and files
+      anyway cannot be found in file-system paths that typically do
+      not follow the namespace naming conventions outlined
+      here).
+
+  - Header files are named after the main class (or object) they
+    define. This also means each header file name starts with a
+    capital letter.
+  
+
+
+## Coding rules
+
+  - Code may not introduce any compiler errors, or warnings
+  - All unit tests must succeed at all times
+  - We use C++14 concepts wherever possible
+    - Class members are initialized at definition
+    - we use "= delete", "= default", etc. identifier in class functions
+  - On any major error or malfunction we throw an exception. This is needed and required for complex physics and shower debugging.
+  - We never catch exceptions for error handling, there might be very few special exceptions from this. We need to discuss such cases.
+  - Everything that should not change should be `const`
+  - Everything that does not need to be visible to the outside of a class/struct should be `private` or `protected`
+  - We prefer the use of references, wherever useful
+  - There cannot be any pointer in the interface of any class or object
+    exposed to outside users, there might be pointers for very special cases
+    inside of classes.
+  - When you contribute new code, or extend existing code, at the same time provide unit-tests for all functionality.
+  - Code must be documented with `doxygen` commands
+  
+
+# How to contribute
+
+  - We organize all development via `Issues` that may be feature requests,
+    ideas, or bugs fix requests. 
+  - New issues can be created, or existing issues
+    picked up. 
+  - Issues are discussed in meetings or via  corsika-devel@lists.kit.edu  within the CORSIKA Project.
+  - Issues are assigned to milestones. 
+  - The work on issues is performed in `branches` that can be best
+    created directly via the gitlab web interface. 
+  - Proposed code to close one issue (located in a specific git
+    branch) is reviewed and eventually discussed, and finally merged
+    into the master branch to close the issue.
+
+
+
+# How to become scientific author of the CORSIKA Project
+
+The CORSIKA Project decides on who becomes scientific author. The
+following conditions are clearly sufficient, but not all of them are
+required all the time:
+  - responsibility for a particular functionality or part
+  - follows these [GUIDELINES](GUIDELINES.md)
+  - agrees to the [COLLABORATION_AGREEMENT](COLLABORATION_AGREEMENT.md)
+  - active in the CORSIKA Project, that means responsive to
+    discussions and problems in corsika-devel@list.kit.edu or on https//gitlab.ikp.kit.edu, of relevant *issues*,
+    or in (phone) meetings
+  - the existing members of the CORSIKA Project agree

SCIENTIFIC_AUTHORS

+(empty...tbd)
+