updates documentation for the library

Author: skyler-ruiter

.github/ISSUE_TEMPLATE.md

@@ -1,32 +1,41 @@
-# Description
+---
+name: Bug report
+about: Report a bug or unexpected behavior
+---
 
-A short human-readable description of the bug.
+## Description
 
-# Versions and Configuration
+A clear description of the bug and what you expected to happen instead.
 
-Contents of `/etc/os-release`:
+## Environment
 
-Output of `cmake -L <build_dir>`:
+**OS** (`cat /etc/os-release` or `uname -a`):
 
-Output of `git log -n 1 --oneline`:
+**GPU** (`nvidia-smi -L`):
 
-GPU and CUDA:
+**CUDA version** (`nvcc --version`):
 
-Output of `nvidia-smi -L`:
+**Compiler** (`gcc --version` or `clang --version`):
 
-Output of `nvcc --version` (or CUDA runtime version):
+**CMake version** (`cmake --version`):
 
-Please include the version information for the following dependencies if installed.
+**FZGPUModules version / commit** (`git log -n 1 --oneline`):
 
-+ compiler (either `gcc` or `clang`)
-+ cmake
-+ Doxygen
+**CMake configuration** (`cmake -L <build_dir>` or the preset and flags you used):
 
-# Steps to Reproduce the Bug
+## Steps to Reproduce
 
-Please provide both:
+1. 
+2. 
+3. 
 
-+ a high level description of how to reproduce the bug including expected vs actual behavior
-+ a short script or Dockerfile to reproduce the bug starting at installing FZGPUModules and its dependencies where possible
+**Expected behavior:**
 
-# Additional Information [Optional]
+**Actual behavior:**
+
+A minimal self-contained reproducer (C++ snippet, test name, or script) is very helpful.
+
+## Additional Context
+
+Logs, stack traces, sanitizer output, or anything else relevant. If you ran under
+AddressSanitizer or Compute Sanitizer, include that output here.

CMakeLists.txt

@@ -88,7 +88,7 @@ if(CMAKE_BUILD_TYPE STREQUAL "Debug")
   set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-unused-variable")
 endif()
 
-option(BUILD_TESTING "Build tests" ON)
+option(BUILD_TESTING "Build tests" OFF)
 if(BUILD_TESTING)
     add_subdirectory(third_party/googletest EXCLUDE_FROM_ALL)
     enable_testing()

CONTRIBUTE.md

@@ -0,0 +1,111 @@
+# Contributing to FZGPUModules
+
+Thanks for your interest in improving FZGPUModules. Contributions of all kinds
+are welcome: bug reports, documentation, examples, tests, and code changes.
+
+---
+
+## Ways to contribute
+
+- **Bug reports** — file an issue with environment details and a minimal reproducer
+- **Documentation** — fix typos, clarify confusing sections, add usage examples
+- **Tests** — add regression tests for existing behavior or cover edge cases
+- **New stages** — see [How to Add a Stage](docs/how_to_add_a_stage.md)
+- **Bug fixes and features** — open an issue to discuss first for non-trivial changes
+
+---
+
+## Build and test
+
+```bash
+# Clone with submodules (googletest)
+git clone https://github.com/szcompressor/FZGPUModules.git
+cd FZGPUModules
+git submodule update --init --recursive
+
+# Build (tests disabled by default; enable explicitly)
+cmake --preset release -DBUILD_TESTING=ON
+cmake --build build/release -j$(nproc)
+```
+
+Run the test suite:
+
+```bash
+ctest --preset default           # all tests
+ctest --preset stages            # stage unit tests only
+ctest --preset pipeline          # pipeline integration tests only
+```
+
+Run with sanitizers before submitting:
+
+```bash
+cmake --preset asan
+cmake --build --preset asan -j$(nproc)
+LD_PRELOAD=$(gcc --print-file-name=libasan.so) \
+  ASAN_OPTIONS=detect_leaks=0:abort_on_error=0:protect_shadow_gap=0 \
+  UBSAN_OPTIONS=print_stacktrace=1:halt_on_error=0 \
+  ctest --preset asan
+```
+
+See [Building from Source](docs/building.md) for preset details and sanitizer flags.
+
+---
+
+## Code style and conventions
+
+- **C++17**, CUDA 11.2+. Match the style of nearby files.
+- **No bare printf/cout/cerr** in library code — use `FZ_LOG(LEVEL, ...)` or `FZ_PRINT(...)`.
+- **No `cudaDeviceSynchronize()`** inside `Stage::execute()` — enqueue all work on the provided `stream`.
+- **Public API only in user-facing code** — include `fzgpumodules.h`; do not include `cuda_check.h` or internal headers in examples.
+- **`connect()` argument order** — `pipeline.connect(downstream, upstream, "port")`.
+- **Lorenzo downstream port** — connect to `"codes"`, not `"output"`.
+- **Template instantiations** — many stages are templates with explicit instantiations (e.g., `RLEStage<uint16_t>`). Check the stage's documentation (e.g., `docs/stages/rle.md`) for available types before using a template stage. Adding a new type requires adding an `extern template` declaration in the header and instantiation in the `.cu` file.
+
+---
+
+## Changelog
+
+For any code change (fix, feature, refactor, removal), add a one-line entry to
+`CHANGELOG.md` under the appropriate `[Unreleased]` subsection (`Added`, `Changed`,
+`Fixed`, or `Removed`) before finishing the change. Documentation-only edits do
+not need a changelog entry.
+
+---
+
+## Adding a new stage
+
+Use the scaffold script and follow the step-by-step guide:
+
+```bash
+scripts/new_stage.sh MyStageName <category>   # category: predictors, quantizers, coders, shufflers, transforms, fused
+```
+
+Full instructions: [docs/how_to_add_a_stage.md](docs/how_to_add_a_stage.md)
+
+Key requirements for any new stage:
+- All required `Stage` virtual methods implemented
+- `StageType` enum value chosen (unique integer, never reuse or renumber existing values)
+- Registered in `StageFactory`, `config.cpp` (TOML), and root `CMakeLists.txt`
+- Tests: ForwardRoundTrip, ZeroInput, SerializeDeserialize, PipelineIntegration, SaveRestoreState
+
+---
+
+## Submitting a pull request
+
+1. Fork and create a branch from `main`.
+2. Make your changes and confirm tests pass (including sanitizers for code changes).
+3. Add a `CHANGELOG.md` entry for code changes.
+4. Open a PR against `main` with a clear description and rationale.
+5. Link any relevant issues; include reproduction steps for bug fixes.
+6. Mention any build flags or environment details required to validate the change.
+
+For non-trivial new features or API additions, open an issue first to discuss the
+approach before writing code — this avoids wasted effort if the design needs revision.
+
+---
+
+## API compatibility
+
+Avoid breaking public API unless the change warrants a major version bump. See
+[API Reference — Stability and Versioning](docs/api_reference.md#api_stability) for the full policy and a
+per-PR checklist.

Doxyfile

@@ -6,8 +6,8 @@
 # Project identity
 #---------------------------------------------------------------------------
 PROJECT_NAME           = "FZGPUModules"
-PROJECT_NUMBER         = "1.0"
-PROJECT_BRIEF          = "GPU-accelerated modular compression pipeline"
+PROJECT_NUMBER         = "2.0"
+PROJECT_BRIEF          = "GPU-accelerated modular compression pipelines"
 OUTPUT_DIRECTORY       = docs/doxygen
 
 #---------------------------------------------------------------------------
@@ -16,6 +16,13 @@ OUTPUT_DIRECTORY       = docs/doxygen
 INPUT                  = include/ \
                          modules/ \
                          docs/mainpage.md \
+                         docs/cli.md \
+                         docs/building.md \
+                         docs/config_file.md \
+                         docs/fzm_format.md \
+                         docs/architecture.md \
+                         docs/api_reference.md \
+                         docs/how_to_add_a_stage.md \
                          docs/stages/
 RECURSIVE              = YES
 FILE_PATTERNS          = *.h *.md