#12 add docs commands
Merged 5 years ago by lenkaseg. Opened 5 years ago by lenkaseg.
lenkaseg/cranc docs  into  master

file modified
+2 -2
@@ -7,6 +7,7 @@ 

  

  from libpagure import libpagure

  

+ <<<<<<< HEAD

  api_token = os.getenv("CRANC_TOKEN")

  project = "pagure"

  
@@ -15,7 +16,6 @@ 

  # Creating a Pagure object

  PAGURE = libpagure.Pagure(pagure_token=api_token, pagure_repository=project)

  

- 

  @click.group()

  def cranc():

      pass
@@ -52,7 +52,7 @@ 

      :return:

      """

      try:

-         return pagure.list_requests(status=status, assignee=assignee, author=author)

+         return PAGURE.list_requests(status=status, assignee=assignee, author=author)

      except Exception:

          _log.exception("Failed to connect to the server")

  

file added
+205
@@ -0,0 +1,205 @@ 

+ # Cranc commands

+ 

+ * conventions:

+ `command <action> <resource>` `command <verb> <noun>`

+ 

+ ## PR

+ 

+ cranc create pr [title] [content]

+ 

+     This command creates a pull request. Its parameters should be: 

+         --title for the pr title, 

+         --content for the description of the pr, 

+         --author for the author flag, 

+         --assignee for assignee

+     # Not in libpagure  

+ 

+ cranc get prs

+ 

+     This command lists all the prs. YOu can list the prs from a specific author by passing 

+         --author flag, 

+         --status filters status of the pr, 

+         --assignee filters assignee of the pr

+ 

+ 

+ cranc merge pr [request_id]

+ 

+     This command merges a pull request. 

+ 

+ 

+ cranc close pr [request_id]

+ 

+     This command closes a pull request without merging.

+ 

+ 

+ cranc flag pr [request_id] [username] [comment] [url]

+ 

+     With this command is possible to add or edit a flag of the pull request. 

+         --request_id specifies the pull request id, 

+         --username specifies the name of the application to be displayed, 

+         --percent specifies the percentage of completion to be displayed, 

+         --comment is a short message sumarizing the flag, 

+         --url specifies a relevant url, 

+         --uid specifies the unique id used to identofy the flag, 

+         --commit specifies the commit to flag on

+ 

+ 

+ ## Issue

+ 

+ cranc create issue [title] [content]

+ 

+     This command creates a new issue. 

+         --title for the issue title, 

+         --content for the description of the issue, 

+         --priority for the priority of the ticket, 

+         --milestone for the milestone of the ticket, 

+         --tags for comma separated list of tag for the ticket, 

+         --assignee for the assignee of the ticket, 

+         --private specifies whether create this issue as private

+ 

+ 

+ cranc get issues

+ 

+     This command lists all the issues of a project. 

+         --status filters the status of the issues, 

+         --tags filters the tags of the issues, 

+         --assignee filters the assignee of the issues, 

+         --milestones filters the milestones of the issues as a list of strings, 

+         --priority filters the priority of the issues, 

+         --no_stones if True returns only the issues having no milestone, in 

+             False returns only the issues witha milestone, 

+         --since filters the issues updated after this date (unix date format 

+             or Y-M-D), 

+         --order sets the ordering of the issues

+ 

+ 

+ cranc edit status [issue_id] [new_status]

+ 

+     This command changes status of an issue. 

+         --issue_id is an id of the issue, 

+         --new_status is the new status of the issue, 

+         --close_status is optional param to add reason why issue has been 

+              closed (like wontfix, fixed, duplicate, ...)

+ 

+ 

+ cranc edit milestone [issue_id] [milestone]

+ 

+     This command changes the milestone of an issue. 

+         --issue_id is an id of the issue, 

+         --milestone is the new milestone for the issue (set None to remove milestone)

+ 

+ 

+ ## Project

+ 

+ cranc create project [name] [description]

+ 

+     This command creates new project on the Pagure instance. 

+         --name for the project name, 

+         --description describes the project, 

+         --namespace for the project to fork, 

+         --url url providing more information about the project, 

+         --avatar_email is an email address for the avatar of the project, 

+         --create_readme is a boolean to specify if there should be a readme 

+             added to the project on creation 

+         --private is a boolean to speficy if the project is private

+ 

+ 

+ cranc get projects

+ 

+     This command lists all the projects on this Pagure instance. 

+         --tags filters the tags of the project, 

+         --pattern filters the projects by the pattern string, 

+         --username filters the username of the project admnistrators, 

+         --owner filters the projects by ownership, 

+         --namespace filters the projects by namespace, 

+         --fork filters whether it is a fork (True or not (False), 

+         --short specifies whether to return the entire JSON or just a subset, 

+         --page speficies that pagination should be turned on and that this 

+             specific page should be displayed, 

+         --per_page specifies the number of projects to return per page (max 100)

+ 

+ 

+ cranc get branches

+ 

+     This command lists all the branches associated with a repository. 

+ 

+ ## Comment

+ 

+ cranc add comment [request_id] or [issue_id] [message]

+ 

+     This command creates a comment on pull request or issue

+         --request_id specifies the id of the pull request, 

+         	--commit specifies which commit to comment on, 

+         	--filename specifies which file to comment on, 

+         	--row specifies the line of code to comment on.

+         --issue_id is an id of an issue

+         --message is the comment body

+ 

+ 

+ cranc get comment [request_id] or [issue_id] [comment_id]

+ 

+     This command gets a specific comment of an issue. 

+         --request_id is an id of the pull request

+         --issue_id id an id of the issue, 

+         --comment_id is an id of the comment

+ 

+ 

+ ## Describe

+ 

+ cranc describe [request_id] or [issue_id]

+ 

+     This command retuns information of a single pull request or issue

+ 

+ 

+ cranc get users

+ 

+     This command lists all the users. 

+ 	--pattern filters the starting letters

+ 

+ 

+ cranc describe user [username] ///this has a bit too many options...maybe better to 

+                                  split it into two commands?

+ 

+     This command gets information about a specific user. 

+ 	--username is the username of the user to get info about

+             --stats retrieves the activity stats about a specific user over the last year

+                 --format allows changing the date/time returned from iso format to 

+ 	            unix timestamp (can be timestamp or isoformat. 

+ 	        --date allows you to see the stats for a specific day.

+ 

+ 

+ cranc get user pr /// maybe cranc get prs --username would cover it?

+ 

+     This command lists pull requests filed by a user. 

+ 	--username is username, 

+ 	--page (int) the page requested (defaults to 1, 

+ 	--status filters the status of pull requests 

+ 	    (default: Open, can be Closed, Merged, All.

+ 

+ 

+ cranc get pr-action [username]  /// Maybe it can be moved to pr resource instead

+ 

+     This command lists pull requests that are actionable by user. 

+ 	--username is username, 

+ 	--page(int) the page requested (defaults to 1), 

+ 	--status filter the status of pull requests 

+ 	    (default: Open, can be Closed, Merged, All.)

+ 

+ 

+ cranc get tags 

+ 

+     This command lists all the tags on this project. 

+ 	--pattern filters the starting letters 

+ 	--project allows you to check tags for a specific project 

+ 	    (instead of the default, which is the current one)

+ 

+ 

+ cranc get groups

+ 

+     This command lists all the groups on this Pagure instance. 

+ 	--pattern filters starting letters

+ 

+ 

+ cranc error

+ 

+     This command provides a dictionary of all error codes

commands.md adjusted to comment in related issue #5

I think I don't not understand the difference between
cranc get prs --author [something] and
`cranc get user pr --[username]

In libpagure they are different functions, I'll look at it.

I made the commands looks more kubectl-like, as proposed. There is a lot of gets and describes. All the commands should be `command <action. <resource> now (except cranc error, dunno if to follow the simpler way or the conventional way with a verb)

rebased onto 702021f

5 years ago

Pull-Request has been merged by lenkaseg

5 years ago
Metadata