New package: Macchiato v0.0.1

[JuliaRegistrator]

• Registering package: Macchiato
• Repository: https://github.com/JuliaMeshless/Macchiato.jl
• Created by: @kylebeggs
• Version: v0.0.1
• Commit: bb4997a045aa946950144ec453fe45430d6f27eb
• Reviewed by: @kylebeggs
• Reference: JuliaMeshless/Macchiato.jl@bb4997a#commitcomment-178489597
• Release notes:

## Features

- Add Oceananigans-style `Simulation` API for running simulations
- Add linear elasticity model with boundary conditions and traction operators
- Add `zero_rows!` utility for O(nnz) sparse row zeroing
- Add Ferrite FEM cantilever beam example for comparison

## Performance

- Share KNN adjacency lists across operators and remove redundant weight updates

## Bug Fixes

- Fix mixed partial operator and body force sign in elasticity
- Handle `SparseVector` returned by RadialBasisFunctions for single evaluation points
- Fix variable naming and `Displacement` constructor in mechanics
- Correct Timoshenko analytical solution in beam example
- Thread RBF basis kwargs through to traction BC operators

## Refactoring

- Unify Dirichlet boundary conditions and simplify BC system with traits
- Remove legacy EquationSet BC compatibility system
- Move test dependencies to separate `test/Project.toml`

## Documentation

- Complete documentation overhaul with source-verified corrections
- Add Custom PDEs guide
- Update PhysicsDomain to EquationSet naming throughout

[github-actions]

Hello, I am an automated registration bot. I help manage the registration process by checking your registration against a set of AutoMerge guidelines. If all these guidelines are met, this pull request will be merged automatically, completing your registration. It is strongly recommended to follow the guidelines, since otherwise the pull request needs to be manually reviewed and merged by a human.

1. New package registration

Please make sure that you have read the package naming guidelines.

2. AutoMerge Guidelines are all met! ✅

Your new package registration met all of the guidelines for auto-merging and is scheduled to be merged when the mandatory waiting period (3 days) has elapsed.

3. To pause or stop registration

If you want to prevent this pull request from being auto-merged, simply leave a comment. If you want to post a comment without blocking auto-merging, you must include the text [noblock] in your comment.

Tip: You can edit blocking comments to add [noblock] in order to unblock auto-merging.

[goerz]

Can I close this in favor of #149605? This does not seem like a v0.0.1 package

[kylebeggs]

@goerz oops. I thought the bot would update the same PR - I guess it does not work like that when it's a new package? I also changed it to v0.0.1 because the bot told me

Ideally, you should register an initial release with 0.0.1, 0.1.0 or 1.0.0 version numbers

so it probably should be 0.1.0?

[goerz]

When you retrigger a registration, anything that changes the package name, URL, UUID, or version number creates a new PR. Anything else (like fixing missing compat bounds most commonly) updates an existing PR.

Ideally, you should register an initial release with 0.0.1, 0.1.0 or 1.0.0 version numbers

That should probably not be mentioning 0.0.1. In fact, we've considered making 0.1.0 the minimum requirement for registrations. Versions <0.1 do not really have a clear meaning. They're not supported by semantic versioning. At least in my interpretation, I would only use 0.0.x versions for "non-functional" releases of a package. For example, when setting up CI infrastructure that needs a "release" to properly be tested. Anything that's functional should really be at least 0.1.

so it probably should be 0.1.0?

From a technical perspective, it doesn't matter very much. Pkg still works with 0.0.x versions, and treats them as "breaking" (which can be pretty annoying for registered packages, because then any release will require release notes detailing the breaking changes). Also, for initial registrations, v0.1 is a natural initial versioning number, but there's no fundamental issue with v0.2 or other v0.x versions. These can make sense if the package has been developed outside of the General registry for some time, and already has tagged releases. If the first tag is v0.2, that raises the obvious question "what happened to v0.1?", and might be pretty confusing to users. Hence the message from the bot.

Some people have argued that registered packages should start with v1.0. They have a point, in that when you're registering a package, you're putting it out for people to depend on. That really requires some level of formal API (which semantic versioning uses as the demarcation point for a v1.0 release), and indeed General requires "breaking" release notes for any v0.x releases (in an extension of semantic versioning, since semantic versioning does not constrain <v1.0 versions to have any sort of formal API with respect to which changes could be breaking or non-breaking). However, my personal view is that an initial version v1.0 is a bit risky for something you're putting out into the public for the first time. When the package is being used as a dependency for the first time in some wider setting, you may very well find out that there are issues with the original API that require some iterations to get right. In my view, it is better to do these iterations in v0.x versions than to go from v1.0 to v10.0 within a few months. As soon as the API is robust, though, a v1.0 release should be tagged. The difference between pre- and post-1.0 is really how PRs are evaluated with respect to "breaking changes". Pre-1.0, the focus should be "anything that makes the API better, with little regard for backwards compatibility". And post-1.0, "try to maintain backwards compatibility unless there is a very good reason to break it.

The most critical requirement for a 1.0 release in my book is that it has a full, formal API documentation. Your package already does, in fact, so with the above considerations, my recommendation is to register with v0.1 (or v0.x if you already have a v0.1 tag in your repo) and then tag a v1.0 release in the relatively near future, after the API has proven itself. Note that going from v0.x to v1.0 does not require breaking changes (and in my view, should avoid them). It's simply a transition from "unstable" to "stable".

If you're pretty sure that the API is good in its current form, you could also register an initial version v1.0.

[noblock]

[kylebeggs]

Fantastic write-up. Thank you very much. I would urge you to put some of the notes in a more permanent place.

I think v0.1 is the correct choice. We are not committed to the API long term yet and thus not ready for 1.0. I also agree skipping to 0.2 would be confusing to users. Can you close this and the other one and I will make a new PR with 0.1?

[goerz]

I would urge you to put some of the notes in a more permanent place.

I've considered putting something on Discourse as a basis for discussion. A lot of that has at least some element of personal opinion, though, and there's not a completely firm consensus on this versioning philosophy, in the General registry or more widely.

Can you close this and the other one and I will make a new PR with 0.1?

I like to keep track of registrations by "Closing in favor of …", but I'll make sure to close them when I see the replacement pop up

[kylebeggs]

see #149638

[goerz]

Closing in favor of #149638