add notes on refactor relative to Framework

refactor-notes.md

@@ -0,0 +1,122 @@
+# Delayed
+Delayed refactors are resolved using some form of
+interopability built with fire.
+
+### Parameters
+The parameters class was updated to shorten the function names.
+- `Framework/Configure/Parameters.h` -> `fire/config/Parameters.h`
+- `getParameter` -> `get`
+- `addParameter` -> `add`
+
+### Storage Hints
+Update the `enum` to a more modern `enum class` design, motivating
+a name change.
+- `framework::hint_shouldDrop` -> `fire::StorageControl::Hint::ShouldDrop`
+- `framework::hint_shouldKeep` -> `fire::StorageControl::Hint::ShouldKeep`
+- ... as well as the other hints that aren't used in ldmx-sw at this time
+
+### Exceptions
+The legacy exception system relied on a macro `EXCEPTION_RAISE` which
+passed the file name, line, and function name into the exception object.
+This is generally considered poor practice because a debugger (like `gdb`)
+can provide this information anyways. The new exception system instead
+allows the user to determine whether to generate the stack trace and it
+avoids using a macro to hide the loss of control to the programmer.
+- `Framework/Exception/Exception.h` -> `fire/exception/Exception.h`
+- `EXCEPTION_RAISE` -> `throw fire::Exception`
+
+### Processors
+The updated processor prototype has a different constructor
+than the legeacy one. The updated construction technique
+reduces the amount of boiler-plate code by hiding the attachment
+of the `Process` handle and putting all configuration into
+the constructor.
+
+You will be forced to update to the new parameters (above),
+but besides that you would simply move the code in `configure`
+into the constructor. The 
+[Getting Started](https://ldmx-software.github.io/fire/md_docs_getting_started.html) page.
+page has details on what the processor structure is.
+
+- `Framework/EventProcessor.h` -> `fire/Processor.h`
+
+### Analyzers
+The updated framework takes a simplifying approach towards the processors
+and the data stream. Instead of having a separate file for storage of binned data
+and ntuples, all of the data will be put into the output file. This effectively makes
+processors that do not modify the event bus useless. See comments below about
+the NtupleManager and HistogramPool. Analyzers are still allowed to compile only
+to allow incremental updates.
+
+### ConditionsObjectProvider
+Pretty much identical comments as Processor since that system
+is so similar to this one. In addition, the new framework shortens
+the name.
+- `Framework/ConditionsObjectProvider.h` -> `fire/ConditionsProvider.h`
+- `framework::ConditionsObjectProvider` -> `fire::ConditionsProvider`
+- `Framework/ConditionsObject.h` -> `fire/ConditionsObject.h`
+- `framework::ConditionsObject` -> `fire::ConditionsObject`
+
+### Logging
+Besides the namespace change, the macro also changed name to reflect
+that the framework is not ldmx-specific anymore.
+- `Framework/Logger.h` -> `fire/logging/Logger.h`
+- `framework::logging::logger` -> `fire::logging::logger`
+- `fire_log` -> `ldmx_log`
+
+### Event
+The event object has changed somewhat mainly to help streamline the calls
+and make what is happening more apparent to the user.
+- `getObject<T>` -> `get<T>`
+- `getCollection<T>` -> `get<std::vector<T>>`
+- `getMap<K,V>` -> `get<std::map<K,V>>`
+
+# Immediate
+These refactors are **not** resolved by inter-op headers within
+fire, so they must be adapted immediately in order to use fire.
+
+### Event and Run Headers
+Shortened function names were introduced with the idea of 
+including more types of header parameters in the future as well.
+- `getFloatParameter` -> `get<float>`
+- `setFloatParameter` -> `set<float>`
+- `getIntParameter` -> `get<int>`
+- `setIntParameter` -> `set<int>`
+- `getStringParameter` -> `get<std::string>`
+- `setStringParameter` -> `set<std::string>`
+
+### Event Objects
+In addition to the ROOT-dictionary macros that are already in all the event objects,
+there are additional changes necessary to do the HDF5-based serialization.
+
+Follow the Data Classes section of the 
+[Getting Started](https://ldmx-software.github.io/fire/md_docs_getting_started.html) page.
+
+The Link Def header that ROOT requires to build the dictionary was previously being
+generated by our CMake infrastructure; however, this was leading to constant confusion
+when attempting to add a new or change a current event object. For this reason, the
+link def header is not written by CMake anymore and should be written manually and committed
+into the repository.
+
+### CMake Changes
+Instead of registering all of the event objects and then constructing a single event
+dictionary, we have each module that wants to define its own event dictionary with
+the `setup_event_library` CMake macro. Since the link def header is being written manually,
+and we aren't joining all of the event objects into a single dictionary, this 
+massively simplifies the CMake code.
+
+### NtupleManager
+**Removed**. Since the destination data format is already ntuple-like in the sense
+that it can be easily analyzed without loading a class dictionary, all processors that
+were adding values to the ntuple manager are instructed to simply write those values to
+the event so that they end up in the output file.
+
+### HistogramPool
+**Removed**. All binning decisions are left to downstream (probably python-based) analyses.
+The `h5py` + `numpy.histogram` ecosystem is very mature and allows for performant histogram
+filling as well as the saving of binned data to a HDF5 file for later loading and plotting.
+
+### EventDef Header
+**Removed**. Separating the event objects into their own event dictionaries and libraries
+makes this centralized header not feasible to produce. Instead, manually include all event
+objects you need. This also helps highlight what your dependencies should be.