[joss_review]: use versioning system

[DaniBodor]

The top of your README states that "While technically complete, AniSOAP is in beta mode, and subject to new changes regularly. Please use with caution as we iron out some of the finer details."

In my mind, while users cannot count on a stable package, the code base is not production ready and should not yet be published on JOSS (@mbobra, could you can weigh in on this, as it's not listed as a formal requirement anywhere). Of course, continuing development should not be in the way of publishing the current package, but this probably be resolved by using semantic versioning (note that a package like bump my version can simplify the process for you). By using a structure workflow, e.g. by isolating new developments away from the main branch until they are production ready, and clearly documenting changes per version, you can both limit the rate of breaking changes and have a simple solution history for users that want to continue working on a given version that works for them.

[mbobra]

I recommend two simple changes, described below, to publish this package in JOSS.

Issuing releases

JOSS requires authors to issue a release upon publication:

When a submission is ready to be accepted, we ask that the authors issue a new tagged release of the software (if changed), and archive it (on Zenodo, figshare, or other).

We do not require authors to adhere to a semantic, or any other, versioning system to tag the release. However, choosing a versioning system doesn't take too much time and it is a good idea. Github defaults to semantic versioning (see point 11 here).

Package stability

The AniSOAP package documentation includes the following warning:

While technically complete, AniSOAP is in beta mode, and subject to new changes regularly. Please use with caution as we iron out some of the finer details.

Incorporating some documentation about the definition of beta mode would be helpful. Does that mean the package will issue new, breaking releases frequently? If so, documenting these breaking changes via release notes is sufficient.

[arthur-lin1027]

Thank you @mbobra and @DaniBodor for this feedback regarding versioning and package stability. I'll definitely add versioning and release notes section in the documentation, and give some thought about how frequently a AniSOAP will have breaking releases.

[ortengren]

@arthur-lin1027 I've created a branch for this issue, but so far I've only removed the old "WARNING" section. As far as semantic versioning, I'm not sure if we would like to include old patches and minor updates in the numbering or if we'd like to start fresh at 1.0.0.

[arthur-lin1027]

Hmm. I'm not sure if 1.0.0 is jumping the gun a bit, but we haven't been super clear on what's just a normal merge vs what additions constitute a patch. Worth discussing with Rosy.