Please deprecate interfaces before breaking backwards compatibility

[hr87]

The Fortran interface has a breaking change between v2.8.2 and 2.9.2. The interface for the Fortran routine adios2_init changed from

adios2_init(adios_object, config_file, communicator, debug_mode, adios_return)

to

adios2_init(adios_object, config_file, communicator, adios_return)

This prevent building the same code with version 2.8.2 and 2.9.2.

I would recommend to mark interfaces as deprecated before removing them. This will alert the user, but does not break code. Additionally, only remove interfaces in major version jumps, e.g. in a jump to v3. Finally, I do not see any note in the changelogs for breaking changes. Add any breaking changes (or deprecation) to the changelog.

A fix for the situation above would be to add the old interfaces back in, even if the debug_mode flag is not used anymore internally.

[eisenhauer]

We were able to tag the old APIs as deprecated in C++, jumping through some hoops to be portable across compilers in C++11 because the official "deprecated" tag isn't supported until C++14. If I recall, such a solution wasn't possible in Fortran due to compiler variation. Unforunately debugMode caused no end of trouble in several bindings, so I don't think it's coming back.

[hr87]

I don't really care about debug mode. I care about doing git bisect an be able to compile without changing the adios dependency.

You can use a runtime warning. This would keep the interface there, so it does not break backwards compatibility, and alert the user. Something like this (will need MPI guards etc)

subroutine adios2_init(adios_object, config_file, communicator, debug_mode, adios_return)

    ! declare variables etc

    print *, 'This interface of adios_init is deprecated and will be removed in version 3. Please update your code. Debug mode has been removed'

    call adios2_init(adios_object, config_file, communicator, adios_return)

end subroutine adios2_init

Also, I do not see this change announced in the change log (maybe I am blind). If you break backwards compatibility, put it in the change log in a prominent location. Breaking changes should be limited to major version changes (2.x.x -> 3.0.0), see here.