Use enum AccessMode for OrgTeam and Collaborator functions (#408)

add docu for breaking change

Use enum AccessMode for OrgTeam and Collaborator functions
and update Team structs

Co-authored-by: 6543 <6543@obermui.de>
Reviewed-on: https://gitea.com/gitea/go-sdk/pulls/408
Reviewed-by: Andrew Thornton <art27@cantab.net>
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>

docs/migrate-v0.12-to-v0.13.md

@@ -10,6 +10,7 @@ feel free to create an issue.
 -   [EditMilestoneOption use StateType (#350)](#EditMilestoneOption-use-StateType)
 -   [RepoSearch Options Struct was rewritten (#346)](#RepoSearch-Options-Struct-was-rewritten)
 -   [Variable Renames (#386)](#Variable-Renames)
+-   [Change Type of Permission Field (#408)](#Change-Type-of-Permission-Field)
 
 <!-- tocstop -->
 
@@ -47,3 +48,14 @@ if you use `CreateOrgOption` somewhere just rename `UserName` to `Name`.
 Pulls:
 
 -   [#386 CreateOrgOption rename UserName to Name](https://gitea.com/gitea/go-sdk/pulls/386)
+
+## Change Type of Permission Field
+
+The following functions are affected:  ListOrgTeams, ListMyTeams, GetTeam, CreateTeam, EditTeam and AddCollaborator
+
+The `Permission` field has changed type from `string` to `AccessMode`, which represent the raw strings you must use before.
+Just replace the string with the AccessMode equivalent.
+
+Pulls:
+
+-   [#408 Use enum AccessMode for OrgTeam and Collaborator functions](https://gitea.com/gitea/go-sdk/pulls/408)

gitea/org_team.go

@@ -12,12 +12,13 @@ import (
 
 // Team represents a team in an organization
 type Team struct {
-	ID           int64         `json:"id"`
+	ID                      int64         `json:"id"`
-	Name         string        `json:"name"`
+	Name                    string        `json:"name"`
-	Description  string        `json:"description"`
+	Description             string        `json:"description"`
-	Organization *Organization `json:"organization"`
+	Organization            *Organization `json:"organization"`
-	// enum: none,read,write,admin,owner
+	Permission              AccessMode    `json:"permission"`
-	Permission string `json:"permission"`
+	CanCreateOrgRepo        bool          `json:"can_create_org_repo"`
+	IncludesAllRepositories bool          `json:"includes_all_repositories"`
 	// example: ["repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.pulls","repo.releases","repo.ext_wiki"]
 	Units []string `json:"units"`
 }
@@ -49,16 +50,39 @@ func (c *Client) GetTeam(id int64) (*Team, error) {
 
 // CreateTeamOption options for creating a team
 type CreateTeamOption struct {
-	Name        string `json:"name"`
+	Name                    string     `json:"name"`
-	Description string `json:"description"`
+	Description             string     `json:"description"`
-	// enum: read,write,admin
+	Permission              AccessMode `json:"permission"`
-	Permission string `json:"permission"`
+	CanCreateOrgRepo        bool       `json:"can_create_org_repo"`
+	IncludesAllRepositories bool       `json:"includes_all_repositories"`
 	// example: ["repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.pulls","repo.releases","repo.ext_wiki"]
 	Units []string `json:"units"`
 }
 
+// Validate the CreateTeamOption struct
+func (opt CreateTeamOption) Validate() error {
+	if opt.Permission == AccessModeOwner {
+		opt.Permission = AccessModeAdmin
+	} else if opt.Permission != AccessModeRead && opt.Permission != AccessModeWrite && opt.Permission != AccessModeAdmin {
+		return fmt.Errorf("permission mode invalid")
+	}
+	if len(opt.Name) == 0 {
+		return fmt.Errorf("name required")
+	}
+	if len(opt.Name) > 30 {
+		return fmt.Errorf("name to long")
+	}
+	if len(opt.Description) > 255 {
+		return fmt.Errorf("description to long")
+	}
+	return nil
+}
+
 // CreateTeam creates a team for an organization
 func (c *Client) CreateTeam(org string, opt CreateTeamOption) (*Team, error) {
+	if err := opt.Validate(); err != nil {
+		return nil, err
+	}
 	body, err := json.Marshal(&opt)
 	if err != nil {
 		return nil, err
@@ -69,16 +93,39 @@ func (c *Client) CreateTeam(org string, opt CreateTeamOption) (*Team, error) {
 
 // EditTeamOption options for editing a team
 type EditTeamOption struct {
-	Name        string `json:"name"`
+	Name                    string     `json:"name"`
-	Description string `json:"description"`
+	Description             *string    `json:"description"`
-	// enum: read,write,admin
+	Permission              AccessMode `json:"permission"`
-	Permission string `json:"permission"`
+	CanCreateOrgRepo        *bool      `json:"can_create_org_repo"`
+	IncludesAllRepositories *bool      `json:"includes_all_repositories"`
 	// example: ["repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.pulls","repo.releases","repo.ext_wiki"]
 	Units []string `json:"units"`
 }
 
+// Validate the EditTeamOption struct
+func (opt EditTeamOption) Validate() error {
+	if opt.Permission == AccessModeOwner {
+		opt.Permission = AccessModeAdmin
+	} else if opt.Permission != AccessModeRead && opt.Permission != AccessModeWrite && opt.Permission != AccessModeAdmin {
+		return fmt.Errorf("permission mode invalid")
+	}
+	if len(opt.Name) == 0 {
+		return fmt.Errorf("name required")
+	}
+	if len(opt.Name) > 30 {
+		return fmt.Errorf("name to long")
+	}
+	if opt.Description != nil && len(*opt.Description) > 255 {
+		return fmt.Errorf("description to long")
+	}
+	return nil
+}
+
 // EditTeam edits a team of an organization
 func (c *Client) EditTeam(id int64, opt EditTeamOption) error {
+	if err := opt.Validate(); err != nil {
+		return err
+	}
 	body, err := json.Marshal(&opt)
 	if err != nil {
 		return err

gitea/pull_review_test.go

@@ -142,7 +142,7 @@ func preparePullReviewTest(t *testing.T, c *Client, repoName string) (*Repositor
 	}
 
 	pullSubmitter := createTestUser(t, "pull_submitter", c)
-	write := "write"
+	write := AccessModeWrite
 	c.AddCollaborator(repo.Owner.UserName, repo.Name, pullSubmitter.UserName, AddCollaboratorOption{
 		Permission: &write,
 	})
@@ -173,7 +173,7 @@ func preparePullReviewTest(t *testing.T, c *Client, repoName string) (*Repositor
 	c.SetSudo("")
 
 	reviewer := createTestUser(t, "pull_reviewer", c)
-	admin := "admin"
+	admin := AccessModeAdmin
 	c.AddCollaborator(repo.Owner.UserName, repo.Name, pullSubmitter.UserName, AddCollaboratorOption{
 		Permission: &admin,
 	})

gitea/repo_collaborator.go

@@ -38,14 +38,39 @@ func (c *Client) IsCollaborator(user, repo, collaborator string) (bool, error) {
 
 // AddCollaboratorOption options when adding a user as a collaborator of a repository
 type AddCollaboratorOption struct {
-	Permission *string `json:"permission"`
+	Permission *AccessMode `json:"permission"`
 }
 
+// AccessMode represent the grade of access you have to something
+type AccessMode string
+
+const (
+	// AccessModeNone no access
+	AccessModeNone AccessMode = "none"
+	// AccessModeRead read access
+	AccessModeRead AccessMode = "read"
+	// AccessModeWrite write access
+	AccessModeWrite AccessMode = "write"
+	// AccessModeAdmin admin access
+	AccessModeAdmin AccessMode = "admin"
+	// AccessModeOwner owner
+	AccessModeOwner AccessMode = "owner"
+)
+
 // Validate the AddCollaboratorOption struct
 func (opt AddCollaboratorOption) Validate() error {
-	if opt.Permission != nil &&
+	if opt.Permission != nil {
-		*opt.Permission != "read" && *opt.Permission != "write" && *opt.Permission != "admin" {
+		if *opt.Permission == AccessModeOwner {
-		return fmt.Errorf("permission mode invalid")
+			*opt.Permission = AccessModeAdmin
+			return nil
+		}
+		if *opt.Permission == AccessModeNone {
+			opt.Permission = nil
+			return nil
+		}
+		if *opt.Permission != AccessModeRead && *opt.Permission != AccessModeWrite && *opt.Permission != AccessModeAdmin {
+			return fmt.Errorf("permission mode invalid")
+		}
 	}
 	return nil
 }