[Refactor] Move Model.prototype.method into Document.prototype.method

[AbdelrahmanHafez]

We currently have functions defined on Model.prototype which can be confusing to people looking at the docs, expecting a specific function to be on the Document section.

AFAICT there is virtually no benefit to defining methods on Model.prototype since Model returns a Document instance, we should define only statics on Model, and leave prototype methods to Document.

Am I missing something here? Let me know if those changes sound reasonable, and I'll put in a PR.

[vkarpov15]

That's fair, I've definitely been confused a few times before by the fact that save() is defined on Model but validate() on Document. I think the original intent was that anything that needs database access should be on Model, but I don't think that's a useful enough distinction for the end user.

If we want to make this change, we should make it in 6.0.

[AbdelrahmanHafez]

What breaking changes will this introduce for the end-user?

If there are not any, making those changes on 6.0 will make merging master into 6.0 a nightmare with many conflicts.

Unless this will introduce breaking changes, I think it'll make the process of keeping 6.0 up-to-date much simpler to do those changes on 5.x.

[vkarpov15]

The primary issue is broken links in the documentation. Anything that links to Model#save() will be broken.

Why will it be a nightmare to merge master into 6.0?

[AbdelrahmanHafez]

The primary issue is broken links in the documentation. Anything that links to Model#save() will be broken.

Unless you're referring to external resources referring to our docs, I think find-and-replace will make the job simple.

Why will it be a nightmare to merge master into 6.0?

Let's take Model#save() as an example, if we do the refactoring on 6.0, with every change that happens to Model#save() on master there will be a conflict on merging master into 6.0, and we'll have to manually copy the modifications from Model#save() into Document#save().

[vkarpov15]

Yeah I mean external resources. Updating our own docs is easy, updating other people's links isn't possible.

Here's an idea: what about just moving the documentation for save() to Document#save()? If we just move the jsdoc comments to document.js, that would be enough to move the documentation and minimize the risk of merge conflicts.

Another option would be to make this change in 6.0 and deal with the merge conflicts as they pop up.

[AbdelrahmanHafez]

I think going to 6.0 will be the overall simpler solution.

[hasezoey]

would moving those function to Document be a breaking change or would it be possible for a minor version?

if its for just a major version, then i would recommend to make this change as one of the last changes (where the branches of the previous major version and the next major version start to differ)

[AbdelrahmanHafez]

Since the only breaking change we're concerned about is the docs URLs breaking, perhaps we can move the functions themselves from Model to Document, and replace the current docs for Model.X with a message saying:

Model.X has moved to Document.X

That way, we won't have to limit ourselves in terms of timeline.

What do you think? @hasezoey @vkarpov15

[hasezoey]

and replace the current docs for Model.X with a message saying:

sounds reasonable, though is it really not breaking anything when the code moved? (like plugin support or something)

[Uzlopak]

If the tests pass?