: No clear way to contribute additional features or open PRs — changes get reset on the next release, and the "topics library" location isn't clear

[Ahmed2398]

As per CONTRIBUTING.md, any additional feature or PR opened against this repo ends up getting reset with the next release, since src/ is generated from a catalog and overwritten on sync. This leaves no real way to contribute to the package.

We need a clear way to actually contribute to this package.

Also, the "topics library" mentioned in the contributing file isn't clear where can it be found?

[IslamBaraka90]

You were right, and it was worse than you knew.

scripts/sync.mjs deletes src/ before it writes, so a PR against it was never going to survive — but CONTRIBUTING.md also told you that src/_shared/ was hand-maintained and safe to edit. That stopped being true when the generator started regenerating it too. The one directory the guide pointed at as yours was the one directory guaranteed to be overwritten. If that is what "prev work is deleted" was about, I am sorry — that one was on the docs, not on you.

I have rewritten the guide and built the routes that were missing. All of it is on main now.

On the "topics library" — that was a documentation bug. The guide told you npm run sync needs a local catalog checkout and separately told you the catalog is private, without naming it or admitting you cannot get one. It is a private monorepo holding each topic's article, implementation, Python sibling, tests and fixtures. A topic there is a lesson, not just a function, and the lesson is the part that stays private.

The code is not private. Every algorithm this package ships is in src/**/impl.ts, byte for byte the catalog file it came from, MIT, and in the npm tarball. There was never an information barrier between you and the implementations — only a question of which file a change could land in.

There are now four ways in, and two of them already worked and were simply undocumented:

1. Tooling, tests, CI, docs — a normal PR. Always worked.
2. A wrong number, with the input that produces it — an issue. It becomes a fixture, which moves a topic from contract to verified.
3. The same result computed faster — a PR to optimised/. New.
4. An algorithm the library does not have — a proposal issue, then a PR. New.

Lane 3 is probably the one you wanted. The catalog implementation is written to be read — it is what the article teaches. A production implementation may want preallocation, a tighter loop, a reused buffer. Those are different jobs, so they no longer have to be the same code.

Drop a file at the subpath the topic publishes:

optimised/technical-indicators/trend-smoothing/sma/impl.ts

On the next sync it ships instead of the catalog's, and the catalog version lands beside it as reference.ts. You only replace the function you are making faster — export * from "./reference.ts" inherits the rest, so an override stays the size of the change. There is a worked example at exactly that path: a real 2.74x on sma, kept in the tree so there is something to copy.

Then the two are held to each other. npm test runs both against the recorded example arguments and against prefixes of every array argument — where warm-up boundaries and reused buffers diverge first — and compares returned values and thrown errors, class and message. It catches a one-index shift in a warm-up boundary, which is how a fast rewrite usually goes wrong. npm run bench prints the ratio against the reference, because "faster" should be a number. Under about 1.2x an override rarely pays for the second implementation.

Lane 4: one step still has to be mine — assigning the topic an id, because ids drive the subpath, the docs URL and the prerequisite order. It takes minutes and happens at the proposal, before you write anything. After that it is a normal PR, and it can ship to npm before the article exists. You do not need to write the article.

Everything except npm run sync runs from a plain clone — tests, coverage, benchmarks, build — because src/, the fixtures and the manifest are all committed.

Thanks for pushing on this. It had been wrong for a while and nobody had said so.

What were you actually trying to change? If it is still open I would like to get it in through one of these rather than leave it.