Open kgryte opened 4 months ago
This should be fine and seems sensible. We will need to ensure to deprecate the various packages already published to npm
.
@Planeshifter Sorry, I have already forgotten. Can our existing automation work with conventional commits? Or do we need to include additional meta information in the commit messages?
@kgryte Currently, we have https://github.com/stdlib-js/metadata-action to process YAML blocks in commit messages, which could be used to build out a method to deprecate packages via the commit messages. We don't have any existing automation for deprecations where the conventional commit deprecate
type would be used to then kick off automatic deprecations. I am also not convinced we really want that, though. Not an everyday occurrence and may be better to perform manually. We have the https://github.com/stdlib-js/stdlib/actions/workflows/deprecate_packages.yml workflow which can be manually invoked with a space separated list of packages to deprecate.
List of deprecated packages:
complex/reviver-float32
complex/float32/reviver
complex/reviver-float64
complex/float64/reviver
complex/parse-float32
complex/float32/parse
complex/parse-float64
complex/float64/parse
complex/base/assert/is-equal
complex/float64/base/assert/is-equal
complex/base/assert/is-equalf
complex/float32/base/assert/is-equal
complex/base/assert/is-not-equal
complex/float64/base/assert/is-not-equal
complex/base/assert/is-not-equalf
complex/float32/base/assert/is-not-equal
complex/base/assert/is-same-value
complex/float64/base/assert/is-same-value
complex/base/assert/is-same-valuef
complex/float32/base/assert/is-same-value
complex/base/assert/is-same-value-zero
complex/float64/base/assert/is-same-value-zero
complex/base/assert/is-same-value-zerof
complex/float32/base/assert/is-same-value-zero
complex/conjf
complex/float32/conj
complex/conj
complex/float64/conj
complex/reimf
complex/float32/reim
complex/reim
complex/float64/reim
complex/imagf
complex/float32/imag
complex/imag
complex/float64/imag
complex/realf
complex/float32/real
complex/real
complex/float64/real
Description
This RFC proposes refactoring the
@stdlib/complex
namespace into separate sub-namespaces forfloat32
andfloat64
.Currently, the
@stdlib/complex
is a flat(ish) namespace, containing top-level packages which are tailored to specific data types.For example, for double-precision complex floating-point numbers, we have
@stdlib/complex/conj
@stdlib/complex/float64
@stdlib/complex/imag
@stdlib/complex/parse-float64
@stdlib/complex/real
@stdlib/complex/reim
@stdlib/complex/reviver-float64
Similarly, we have equivalent packages for single-precision complex floating-point numbers.
Accordingly, in order to distinguish double- and single-precision variants, we resort to suffixes (e.g.,
*f
or-floatXX
). This has worked fine and mirrors@stdlib/math/base/special/*
.However, this structure departs from the structure of
@stdlib/number/*
, where number dtypes and their associated functionality is broken down into sub-namespaces. This has the advantage in that we can avoid suffix name pollution and have similarly named packages across each of the different numeric data types. This will be especially useful when we add base operations (e.g.,@stdlib/number/int32/base/add
), where for many numeric dtypes (e.g.,int8
,uint8
, etc), we don't have suffix conventions (i.e., we have noint8
equivalent off
and are unlikely to ever have such an equivalent).Accordingly, what this RFC proposes is a refactoring of the
@stdlib/complex/*
namespace to match the@stdlib/number/*
namespace. E.g.,@stdlib/complex/float64/ctor
@stdlib/complex/float64/real
@stdlib/complex/float64/imag
@stdlib/complex/float64/add
@stdlib/complex/float32/ctor
@stdlib/complex/float32/real
(no suffix!)@stdlib/complex/float32/imag
(no suffix!)@stdlib/complex/float32/add
(no suffix!)@stdlib/complex/ctors
@stdlib/complex/cmplx
@stdlib/complex/reviver
where we keep the APIs which operate on or return either complex dtype at the top-level.
A consequence of this refactoring is that it should help make things a bit cleaner in the top-level
@stdlib/complex
namespace when adding support for half-precision complex floating-point numbers (as needed based on future inclusion ofFloat16Array
in ECMAScript) and allow us to avoid needing to use a new suffix to differentiate the associated APIs.As it is, that
@stdlib/number
and@stdlib/complex
are organized differently has been a source of friction for me and having organizational parity seems more intuitive.Related Issues
No.
Questions
No.
Other
The migration path would be as follows:
@stdlib/complex/float32
and@stdlib/complex/float64
to@stdlib/complex/float32/ctor
and@stdlib/complex/float64/ctor
, respectively.require
paths using those packages.require
paths using the dtype-specific complex packages.@stdlib/complex
namespace.cc @Planeshifter
Checklist
RFC:
.