.. highlight:: shell

============
Contributing
============

Contributions are welcome, and they are greatly appreciated! Every
little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions
----------------------

Report Bugs
~~~~~~~~~~~

Report bugs at https://github.com/Chaffelson/nipyapi/issues.

If you are reporting a bug, please include:

* Your operating system name and version.
* Any details about your local setup that might be helpful in troubleshooting.
* Detailed steps to reproduce the bug.

Fix Bugs
~~~~~~~~

Look through the GitHub issues for bugs. Anything tagged with "bug"
and "help wanted" is open to whoever wants to implement it.

Implement Features
~~~~~~~~~~~~~~~~~~

Look through the GitHub issues for features. Anything tagged with "enhancement"
and "help wanted" is open to whoever wants to implement it.

Write Documentation
~~~~~~~~~~~~~~~~~~~

Nipyapi could always use more documentation, whether as part of the
official Nipyapi docs, in docstrings, or even on the web in blog posts,
articles, and such.

Submit Feedback
~~~~~~~~~~~~~~~

The best way to send feedback is to file an issue at https://github.com/Chaffelson/nipyapi/issues.

If you are proposing a feature:

* Explain in detail how it would work.
* Keep the scope as narrow as possible, to make it easier to implement.
* Remember that this is a volunteer-driven project, and that contributions
  are welcome :)

Get Started!
------------

Ready to contribute? Here's how to set up `nipyapi` for local development.

1. Fork the `nipyapi` repo on GitHub.
2. Clone your fork locally::

    $ git clone git@github.com:Chaffelson/nipyapi.git

3. Create and activate a Python 3.9+ virtual environment (venv or conda), then install dev extras::

    # using venv
    $ python -m venv .venv && source .venv/bin/activate
    $ cd nipyapi/
    $ pip install -e ".[dev]"

    # or using conda
    $ conda create -n nipyapi-dev python=3.11 -y
    $ conda activate nipyapi-dev
    $ pip install -e ".[dev]"

4. Create a branch for local development::

    $ git checkout -b name-of-your-bugfix-or-feature

   Now you can make your changes locally.

5. You may want to leverage the provided Docker profiles for testing and development

 - Install the latest version of Docker
 - Use the provided Docker Compose configuration in `resources/docker/compose.yml` and run tests via Makefile::

    # generate local test certificates (run once or after cleanup)
    $ make certs

    # bring up single-user profile and wait for readiness
    $ make up NIPYAPI_PROFILE=single-user
    $ make wait-ready NIPYAPI_PROFILE=single-user
    # run tests (conftest resolves URLs, credentials, and TLS for the profile)
    $ make test
    # bring everything down when done
    $ make down


6. When you're done making changes, run the test suites for all profiles::

    # convenience shortcuts
    $ make test-all

7. Commit your changes and push your branch to GitHub::

    $ git add .
    $ git commit -m "Your detailed description of your changes."
    $ git push origin name-of-your-bugfix-or-feature

8. Submit a pull request through the GitHub website.

Common Mistakes to Avoid
------------------------

When contributing to NiPyAPI, watch out for these frequent pitfalls:

**Installation & Environment**

* **Bracket quoting in zsh**: Running ``pip install -e .[dev]`` fails in zsh due to glob expansion. Always use quotes: ``pip install -e ".[dev]"`` or use ``make dev-install``.
* **Wrong Python version**: Project supports Python 3.9-3.12. Using 3.8 (end of life) or 3.13+ (untested) may cause compatibility issues.
* **Missing virtual environment**: Always activate a virtual environment before installing dependencies to avoid polluting system Python.

**Testing**

* **Missing NIPYAPI_PROFILE**: Never run ``pytest`` without setting ``NIPYAPI_PROFILE`` environment variable. Always use ``make test NIPYAPI_PROFILE=single-user`` or equivalent.
* **Services not ready**: Never assume Docker services are immediately ready after ``make up``. Always run ``make wait-ready NIPYAPI_PROFILE=<profile>`` before testing.
* **Stale certificates**: If you encounter certificate errors, run ``make down`` then ``make certs`` to regenerate fresh certificates. Never run ``make certs`` while containers are running.

**Code Quality**

* **Modifying generated code**: Never edit files in ``nipyapi/nifi/``, ``nipyapi/registry/``, or ``nipyapi/_version.py``. These are auto-generated and your changes will be overwritten.
* **Skipping lint checks**: Always run ``make lint`` before committing. Both flake8 and pylint must pass.
* **Incorrect line length**: Project uses 100-character line limit consistently across all tools (flake8, pylint, black, isort).

**NiFi vs Registry Security Differences**

**Important:** NiFi and Registry have different security implementations in their OpenAPI specifications:

* **NiFi 2.6.0+**: Includes native security schemes (``HTTPBearerJWT``, ``CookieSecureAuthorizationBearer``) in base OpenAPI spec
* **Registry 2.6.0+**: Has NO security schemes in base OpenAPI spec - requires augmentation

**Key implications:**

* Registry augmentation scripts (``resources/client_gen/augmentations/registry_security.py``) remain necessary even though NiFi 2.6.0 has native security
* Both services use the same authentication flow: username/password → JWT token → Bearer auth
* The template (``configuration.mustache``) handles both cases via hardcoded ``bearerAuth`` fallback plus native scheme aliases
* Always use ``augmented`` variant when regenerating clients (default) to support both NiFi and Registry
* NiFi can work without augmentation using the ``base`` variant (2.6.0+), but Registry cannot

**Docker & Infrastructure**

* **Docker volume caching**: If you experience persistent issues, run ``make clean-docker`` to remove all containers and volumes, then restart the setup process.
* **Wrong profile for test**: Ensure your ``NIPYAPI_PROFILE`` matches the profile you started with ``make up``. Mixing profiles causes authentication failures.

Make Targets Quick Reference
-----------------------------

NiPyAPI uses Makefile targets as the primary automation interface. Run ``make help`` to see all available targets organized by category.

**Setup & Installation**
::

    make dev-install      # Install package with dev dependencies (recommended)
    make docs-install     # Install documentation dependencies
    make clean            # Remove build, pyc, and temp artifacts
    make clean-all        # Nuclear clean: removes ALL including generated code

**Testing Workflow**
::

    # Basic test workflow
    make certs                              # Generate certificates (once)
    make up NIPYAPI_PROFILE=single-user     # Start Docker services
    make wait-ready NIPYAPI_PROFILE=single-user  # Wait for readiness
    make test NIPYAPI_PROFILE=single-user   # Run tests
    make down                               # Stop services

    # Shortcuts for specific profiles
    make test-su          # single-user profile
    make test-ldap        # secure-ldap profile
    make test-mtls        # secure-mtls profile

    # Comprehensive testing
    make test-all         # Run all automated profiles (single-user, ldap, mtls)
    make coverage         # Run tests with coverage report

**Code Quality**
::

    make lint             # Run flake8 + pylint (excludes generated code)
    make flake8           # Run flake8 only
    make pylint           # Run pylint only
    make pre-commit       # Run pre-commit hooks on all files

    # Formatting (manual)
    black nipyapi/ && isort nipyapi/  # Auto-format code

**Docker Operations**
::

    make certs            # Generate PKCS12 certificates for secure profiles
    make up NIPYAPI_PROFILE=<profile>    # Start specific profile
    make down             # Stop all Docker services
    make wait-ready NIPYAPI_PROFILE=<profile>  # Wait for services to be ready
    make clean-docker     # Comprehensive Docker cleanup

    # Available profiles: single-user, secure-ldap, secure-mtls, secure-oidc

**Build & Documentation**
::

    make dist             # Build wheel and source distribution
    make check-dist       # Validate distribution files
    make test-dist        # Test that distribution can be imported
    make docs             # Generate Sphinx documentation

**Complete Workflows**
::

    make sandbox NIPYAPI_PROFILE=single-user  # Create sandbox with sample objects
    make rebuild-all      # Comprehensive rebuild: clean → certs → APIs → clients → test → build → docs

Generated vs Maintained Code
-----------------------------

Understanding which code is generated vs maintained is crucial for contributing:

**Generated Code (DO NOT MODIFY)**

These files are automatically generated from OpenAPI specifications and should never be edited directly:

* ``nipyapi/nifi/`` - NiFi API client
* ``nipyapi/registry/`` - Registry API client
* ``nipyapi/_version.py`` - Git version via setuptools-scm

**Why this matters:**

1. Your changes will be overwritten during the next client generation
2. These files are excluded from linting (flake8, pylint, black, isort)
3. Test coverage doesn't include generated code
4. Pull requests should not modify these paths

**Maintained Code (Where to Contribute)**

Focus your contributions on these core modules:

* ``nipyapi/canvas.py`` - Canvas management functions
* ``nipyapi/config.py`` - Configuration and endpoints
* ``nipyapi/parameters.py`` - Parameter context operations
* ``nipyapi/profiles.py`` - Profile management system
* ``nipyapi/security.py`` - Authentication and security
* ``nipyapi/system.py`` - System-level operations
* ``nipyapi/utils.py`` - Utility functions
* ``nipyapi/versioning.py`` - Version control operations
* ``tests/`` - Test suite (always add tests for new features)
* ``examples/`` - Example scripts and usage patterns
* ``docs/`` - Documentation (RST files)

**Regenerating Clients**

If you need to update the generated clients (e.g., for a new NiFi version):
::

    # Set target NiFi version
    export NIFI_VERSION=2.5.0

    # Fetch and generate
    make fetch-openapi      # Fetch specs from running NiFi
    make gen-clients        # Generate Python clients

    # Test with new clients
    make test-all

**Augmentation System**

The project includes an augmentation system for fixing OpenAPI spec issues:

* Base specs: ``resources/client_gen/api_defs/nifi-<version>.json``
* Augmentations: ``resources/client_gen/augmentations/*.py``
* Augmented specs: ``resources/client_gen/api_defs/*-<version>.augmented.json``

If you find spec issues, contribute fixes to the augmentation scripts rather than modifying generated code.

Pull Request Guidelines
-----------------------

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put
   your new functionality into a function with a docstring, and add the
   feature to the list in README.rst.
3. The pull request should pass lint and all three profile test suites (use `make lint` and `make test-su`, `make test-ldap`, `make test-mtls`).
   Exceptions (e.g., docs-only changes) should note why profile tests were skipped.
4. Pull requests should be created against 'main' branch for new features or work with NiFi-2.x, or maint-0.x for critical patches to NiFi-1.x featuers.