Description of what Wiby does and how it achieves this needs improvement

[ghinks]

I had not been contributing to Wiby as I had other commitments during 2020 and so I came a fresh perspective ( meaning I did not really understand it at first).

What I think is needed is refresh of the readme so that it is more obvious what wiby does for a prospective user and how that is achieved.

I know it is early days at the moment but the readme file is the window into the tool and is equally as important as the code itself.

What we need to highlight is

• Wiby's purpose and why you would want to use it
• How it works, equally important so that folks want to use it
• Many examples

[ghinks]

I am going to work on this.

I think small updates that make it easy to review would be the best approach.

[ghinks]

Progress

I am taking a first pass on the documentation, after a bit of hiatus, making it a bit more digestible for someone without knowledge of the project. Update to the readme are here in my clone. As I go through the exercise important points are being raised.

Issues found during documentation, or items we need to think about

• We are github centric and we should call this out. Meaning, we make assumptions about where the repositories are.
• In general dependencies usually refer to npm modules. but we could have repo dependencies of other repo dependents, and this may need documenting
• a significant section on the .wiby.json format is needed coupled with the command line options
• address complex repo dependents that use modules created from build pipelines that have typescript or other transpiled steps.

Next Sections in the examples

What I intend to do is cover all the basic commands that wiby has

• clean
• close
• test
• validate
• result

Just the basics of each , why these commands are available, how to use them and what they do.

[dominykas]

Thanks for doing this!

We are github centric and we should call this out. Meaning, we make assumptions about where the repositories are.

This is true - but I'd love to reduce that, e.g. we could replace direct Github API calls when creating commits with raw git commands.

In general dependencies usually refer to npm modules. but we could have repo dependencies of other repo dependents, and this may need documenting

Not following this - can you please elaborate?

a significant section on the .wiby.json format is needed coupled with the command line options

I think one word is not necessary here, but I'm not sure which one 😂

address complex repo dependents that use modules created from build pipelines that have typescript or other transpiled steps.

This should all be happening in CI regardless? Unless you mean we need to take into account folks who commit the build artifacts into git?

---

Scanning through the README, some notes:

The wiby program exists to create a notification to the dependent package maintainers of changes made in a dependency.

This is not exactly true. We want to minimize the disruption for dependent package maintainers. We want the maintainer of the dependency to have a way to figure out if they might be introducing an unintended breaking change. This is especially relevant for things like fastify, where a change in the core framework might unintentionally result in regressions when used with plugins, etc.

By running wiby, the authors of a dependency will know whether they need to bump major (if dependents break) or alternatively they might have to introduce some fixes to avoid the breaking changes.

example-dependency-id-a, example-dependent-id-a

This has been bothering me for a long time... But I find the dependent vs dependency wording hard to understand at a glance. I know these are industry wide terms, but I wonder if we can find some synonyms or generally a better way to express this? Parent/child is not exactly the right thing either, although we have parent/dependency scattered across the codebase... Maybe there's a way to come up with more concrete examples, as opposed to using abstract terminology? Are there any well known packages that we could use as examples? Even if it's e.g. wiby and tap? Or possibly lodash as the dependency, and pretty much anything as a dependent? Or better yet, something that we have in this org - detect-node-support depends on @pkgjs/nv?

Alternatively, maybe using application vs library as a more abstract concept? Or framework vs plugin? Just that if we go half-way abstract, it might not be obvious enough that the tool itself is more than that...

[ljharb]

I think that the thing i run wiby on is a library. It has dependencies (irrelevant here) and dependents (what wiby tests).

[ghinks]

I have raised a PR 112 and am still working on it.