Project Stability

[darsor]

One concern I have about introducing Orbit at work is the current project stability, or lack thereof. Understanding that it has not yet reached a stable 1.0, are there any plans or goals for stability pre-1.0?

For example, the latest release includes this change:

Renames source field to repository field within a project's manifest

This is fine, since again this is pre-1.0. But are all my cores from the previous version now broken/incompatible since they don't have a "repository" field in the manifest?

What I'd like is an explicit statement or project approach for these types of changes. For example, is the "source" field still accepted but deprecated? If so, when will it be removed? Etc.

[chaseruskin]

I do apologize for this breaking change; I realize as more people begin to use the tool, then changes like this, especially fields interfacing with the deployment/publishing aspect of the tool, become a headache to migrate and update. Moving forward, I can say the current manifest entries (Orbit.toml) and configuration entries (config.toml) are fairly stable with non-breaking changes for the long-term. This one change in terminology was to be more consistent with other package managers as well as provide a more descriptive name than what some may consider to be vague. Regarding stability, the one thing that is still up in the air in my opinion is the publishing/channel aspect of the tool; this area may still experience some refactoring until an official 1.0.0 release as it has not yet really been tested in a real setting (although it seems like now it is!). I do agree though that it should try to issue warnings/paths forward to convert any breaking changes in coming releases to ensure compatibility over time.

One path forward may be to publicly open issues or discussions on GitHub whenever a breaking change is considered to the manifest and/or critical areas of the project; this will allow others to voice feedback and concerns about future design decisions as they come up.

For this case, the source field is now deprecated. In general, while on version 0.*.*, I try to use the minor number to represent critical breaking changes, and the patch number to represent backward-compatible updates and bug fixes. I'll do a better job making sure compatibility is carefully considered when thinking of future changes.

[chaseruskin]

After some more thought, I am unsure if this field should be called repository or left as source. Maybe I jumped to the gun to rename it, but the intention behind the field is to specify a remote location of how to access the project from the internet. A lot of package managers build in the assumption of using some form of version control (mainly git), but with Orbit, I thought it would be best if users can configure whatever version control they are using (or none), especially since some still use SVN. This brought the idea of having the concept of protocols be introduced such that users can configure exactly how to download projects from the internet. By allowing protocols as an external configuration, it also alleviates some complexity within Orbit while allowing users more flexibility. For the value of this field, a common example I assume is using the git repository URL if a project is using git (and having an accompanying protocol set up to git clone with this value), but other options are valid such as SVN repositories, or just straight up URLs to zip files (which I guess is not technically a repository?). This makes me wonder if the name should really just be source to encapsulate all the possible ways one could identify a location for a project on the internet. How were you using the field before, and did you end up using it a lot throughout your projects already?

[darsor]

I didn't feel like the name source was misleading or confusing when I used it. And I agree that repository might be a little too specific.

I ended up creating a custom protocol that takes a git repo. It assumes the repo is set up in a specific way (mainly where packages live in the repo) and uses git bisect while parsing the manifest to find the first commit with the target version. The idea was to make it possible to have multiple small IPs in one git repository, to reduce the overhead of a single managing a separate repo for each IP.

[darsor]

I'm definitely not advocating for avoiding breaking changes pre-1.0. But I do think at this point they should be handled with care. For example, if you stick with the repository field I'd still allow source as an alias and put a deprecation notice in the docs. Then I'd remove source later, probably I'm the 1.0 release.

[chaseruskin]

I'm definitely not advocating for avoiding breaking changes pre-1.0. But I do think at this point they should be handled with care. For example, if you stick with the repository field I'd still allow source as an alias and put a deprecation notice in the docs. Then I'd remove source later, probably I'm the 1.0 release.

I agree with that approach moving forward after we reverse this action real quick. I'll put out a release in the coming week putting source back in as the field; it is fine how it was. I was trying to find the package manager I remember seeing also call it source and it was luarocks that has something kind of similar.

For now I recommend still using version 0.26.3 until 0.28.0 comes out.