Clarify distinction between legacy proposals and non-legacy proposals

[rootulp]

Context

cosmos-sdk/x/gov/README.md

Lines 495 to 501 in b18b6c4

	### Legacy Proposal
	A legacy proposal is the old implementation of governance proposal.
	Contrary to proposal that can contain any messages, a legacy proposal allows to submit a set of pre-defined proposals.
	These proposal are defined by their types.
	While proposals should use the new implementation of the governance proposal, we need still to use legacy proposal in order to submit a `software-upgrade` and a `cancel-software-upgrade` proposal.

Question

I'm confused on the difference between legacy proposals and non-legacy proposals. This section indicates that a legacy proposal is for software-upgrade and a cancel-software-upgrade.

1. Is MsgSoftwareUpgrade the type that this is referring to? If yes, would it help clarify that this type is legacy with the word "deprecated" in the godoc?
2. What is the difference between types/v1 and types/v1beta1? When should each be used?

[julienrbrt]

While proposals should use the new implementation of the governance proposal, we need still to use legacy proposal in order to submit a software-upgrade and a cancel-software-upgrade proposal.

This is outdated, and this mention can be removed.

1. No, this is a gov v1 proposal. A gov v1beta1 proposal looks like this:

   cosmos-sdk/x/upgrade/types/proposal.go

   Line 13 in b18b6c4

   func NewSoftwareUpgradeProposal(title, description string, plan Plan) gov.Content {

   /

   cosmos-sdk/x/upgrade/types/upgrade.pb.go

   Line 97 in b18b6c4

   type SoftwareUpgradeProposal struct {

   
   Both are supported by the gov module.
2. You should simply use msgs as proposals (i.e gov v1).

[rootulp]

Both are supported by the gov module.

Is one form considered legacy and/or deprecated? Sorry I still don't understand the difference between v1 and v1beta1 types, can you please re-clarify?

[rootulp]

Proposals:

1. Can NewSoftwareUpgradeProposal be renamed to include the word "legacy"?

   cosmos-sdk/x/upgrade/types/proposal.go

   Line 13 in b18b6c4

   func NewSoftwareUpgradeProposal(title, description string, plan Plan) gov.Content {

2. Can the godoc for NewSoftwareUpgradeProposal describe that it is "legacy" or deprecated?

[julienrbrt]

Hey, the type itself SoftwareUpgradeProposal, is deprecated. I do not see why not renaming the constructor however if it makes the API clearer.

Is one form considered legacy and/or deprecated? Sorry I still don't understand the difference between v1 and v1beta1 types, can you please re-clarify?

Yes, the v1beta1 form is legacy and deprecated. The difference is that gov v1 can handle any msg as proposals, and gov v1beta1 can only handle a list of registered proposal messages.

[rootulp]

I do not see why not renaming the constructor however if it makes the API clearer.

I think renaming NewSoftwareUpgradeProposal to NewLegacySoftwareUpgradeProposal would make the API clearer. Additionally, I think the godoc should mention "legacy" or deprecated. I'm happy to open an issue or PR if its helpful.

[julienrbrt]

I do not see why not renaming the constructor however if it makes the API clearer.

I think renaming NewSoftwareUpgradeProposal to NewLegacySoftwareUpgradeProposal would make the API clearer. Additionally, I think the godoc should mention "legacy" or deprecated. I'm happy to open an issue or PR if its helpful.

Feel free to open a PR and reference this comment.