From 1e261a89398e3d44f49c4c7183adaf97cbbec5be Mon Sep 17 00:00:00 2001 From: pac23 Date: Jul 05 2019 12:18:23 +0000 Subject: Documentation first draft --- diff --git a/Docs/antora.yml b/Docs/antora.yml new file mode 100644 index 0000000..f5d64d9 --- /dev/null +++ b/Docs/antora.yml @@ -0,0 +1,10 @@ +name: Fedora-change-wrangler-docs + +title: Fedora-change-wrangler-docs + +version: master + +start_page: ROOT:index + +nav: + - modules/ROOT/nav.adoc \ No newline at end of file diff --git a/Docs/build.sh b/Docs/build.sh new file mode 100644 index 0000000..05e4e7c --- /dev/null +++ b/Docs/build.sh @@ -0,0 +1,90 @@ +#!/bin/sh + + +image="docker.io/antora/antora" + +cmd="--html-url-extension-style=indexify site.yml" + + + +if [ "$(uname)" == "Darwin" ]; then + + # Running on macOS. + + # Let's assume that the user has the Docker CE installed + + # which doesn't require a root password. + + echo "" + + echo "This build script is using Docker container runtime to run the build in an isolated environment." + + echo "" + + docker run --rm -it -v $(pwd):/antora $image $cmd + + + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + + # Running on Linux. + + # Check whether podman is available, else faill back to docker + + # which requires root. + + + + if [ -f /usr/bin/podman ]; then + + echo "" + + echo "This build script is using Podman to run the build in an isolated environment." + + echo "" + + podman run --rm -it -v $(pwd):/antora:z $image $cmd + + + + elif [ -f /usr/bin/docker ]; then + + echo "" + + echo "This build script is using Docker to run the build in an isolated environment." + + echo "" + + + + if groups | grep -wq "docker"; then + + docker run --rm -it -v $(pwd):/antora:z $image $cmd + + else + + echo "" + + echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password." + + echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/." + + echo "" + + sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd + + fi + + else + + echo "" + + echo "Error: Container runtime haven't been found on your system. Fix it by:" + + echo "$ sudo dnf install podman" + + exit 1 + + fi + +fi \ No newline at end of file diff --git a/Docs/modules/ROOT/nav.adoc b/Docs/modules/ROOT/nav.adoc new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/Docs/modules/ROOT/nav.adoc @@ -0,0 +1 @@ + diff --git a/Docs/modules/ROOT/pages/Accept/accepting-changes.adoc b/Docs/modules/ROOT/pages/Accept/accepting-changes.adoc new file mode 100644 index 0000000..148179f --- /dev/null +++ b/Docs/modules/ROOT/pages/Accept/accepting-changes.adoc @@ -0,0 +1,34 @@ +ifdef::context[:parent-context: {context}] +:context: accepting-changes + += Accepting Changes in the Tool + +Accept command enables the user to accept a change proosal. It takes the issue no as a argument and initiates the convert functionality followed by creating the issue in bugzilla linked with the pagure repo. + +== Usage + +include::config.note.adoc[] + +Accept has only once command that does everything mentioned in the above sections + +Accepts the Change Converts Issue to UserStory creates a Bug in bugzilla +"X" stands for issue Refrence/No from taiga + ++ +---- +fedora-change-wrangler accept --accept "X" +---- + + + +The --accept flag is to let the system know that you are passing N number of issue no's. + +The --config can be passed as ++ +---- +fedora-change-wrangler accept --accept "X" --config +---- + + + + diff --git a/Docs/modules/ROOT/pages/Announce/announce-mailinglist.adoc b/Docs/modules/ROOT/pages/Announce/announce-mailinglist.adoc new file mode 100644 index 0000000..8e5e483 --- /dev/null +++ b/Docs/modules/ROOT/pages/Announce/announce-mailinglist.adoc @@ -0,0 +1,38 @@ +ifdef::context[:parent-context: {context}] +:context: annoucing-mailinglist + += Annoucing to the Mailing list + +The Annouce command announces to the Mailing list. It takes the issue refrence no as a argument and initiates the mailing functionality.It will fetch the issue with its description,summary and all other attributes and send a mail as per the predefined email id list in the config. + +== Usage + +include::config.note.adoc[] + +Accept has only one command that does everything mentioned in the above sections + +Announces the Issue to the mailing list +"X" stands for issue Refrence/No from taiga + ++ +---- +fedora-change-wrangler announce --ml "X" +---- + +Announces the Issue to the mailing list but with the reply header + +--reply if not mentioned has the reply option for all emails, +if set only the first email adress is set as reply to in the header + ++ +---- +fedora-change-wrangler announce --ml "X" --reply +---- + +The --config header as mentioned in the note above can also be used with all these. + ++ +---- +fedora-change-wrangler announce --ml "X" --reply --config +---- + diff --git a/Docs/modules/ROOT/pages/Auth/authenticate-bugzilla.adoc b/Docs/modules/ROOT/pages/Auth/authenticate-bugzilla.adoc new file mode 100644 index 0000000..b84deb0 --- /dev/null +++ b/Docs/modules/ROOT/pages/Auth/authenticate-bugzilla.adoc @@ -0,0 +1,11 @@ +ifdef::context[:parent-context: {context}] +:context: authentica-bugzilla + += Authenticate Bugzilla + +Bugzilla authentication is handled by the python-bugzilla module +It will ask for the user id and password from the user whenver a function that has the bugzilla functionality is used and saves the token fetched from it in a cookie. +For more information checkout the link_here[Developer-Documentation] + + + diff --git a/Docs/modules/ROOT/pages/Auth/authenticate-pagure.adoc b/Docs/modules/ROOT/pages/Auth/authenticate-pagure.adoc new file mode 100644 index 0000000..8796a1f --- /dev/null +++ b/Docs/modules/ROOT/pages/Auth/authenticate-pagure.adoc @@ -0,0 +1,32 @@ +ifdef::context[:parent-context: {context}] +:context: authenticate-pagure + += Authenticate Pagure + +Pagure requires using a token/key to acess the Rest api.The key is unique to each repository. +The auth command with the pagure flag and its subcommands sets the api token for the specfic repositories. + +include::config.note.adoc[] + +=== Set or Reset Taiga Credentials + +The API key is required for creating/delteting issues and other enabled functions on the repository.The token is stored securly in your system. + +For More information on the technical details of the storage kindly read the link_here[Developer Documentation] + +To set/reset the token : + ++ +---- +fedora-change-wrangler auth pagure --reset +---- + +=== Test if token is valid + +Using this command one may test the set api key/token.This command returns information of the user the repository tied to the api key. + ++ +---- +fedora-change-wrangler auth pagure --whoami +---- + diff --git a/Docs/modules/ROOT/pages/Auth/authenticate-taiga.adoc b/Docs/modules/ROOT/pages/Auth/authenticate-taiga.adoc new file mode 100644 index 0000000..31fa1f0 --- /dev/null +++ b/Docs/modules/ROOT/pages/Auth/authenticate-taiga.adoc @@ -0,0 +1,35 @@ +ifdef::context[:parent-context: {context}] +:context: authenticate-taiga + += Authenticate Taiga + +Taiga requires using a token/key to acess the Rest api. +The auth command with the --taiga flag and its sublags retrive the token or refresh it if expired. + +include::config.note.adoc[] + +=== Set or Reset Taiga Credentials + +The Credentials required for fetching the token are stored securly in your system.The users Taiga Username and Password would be required to +fetch the token. + +For More information on the technical details of the storage kindly read the link_here[Developer Documentation] + +To set/reset the token : + ++ +---- +fedora-change-wrangler auth taiga --reset +---- + +=== Refresh Expired Taiga Api Token + +Taiga's token expires every 60 days so it needs to be refreshed. + +To refresh the token: + ++ +---- +fedora-change-wrangler auth taiga --token +---- + diff --git a/Docs/modules/ROOT/pages/Config/Config-set.adoc b/Docs/modules/ROOT/pages/Config/Config-set.adoc new file mode 100644 index 0000000..49412e2 --- /dev/null +++ b/Docs/modules/ROOT/pages/Config/Config-set.adoc @@ -0,0 +1,47 @@ +ifdef::context[:parent-context: {context}] +:context: config-set + += Config + +The Tool has user defined settting available via the config.The config allows the user to have the tool work with thier own instances of Taiga,Pagure and Bugzilla. +It also allows the user to set the sender,reciver email id's for email funcitonality, + +=== User Defined Config Storage +The config can also be stored in a user defined location and the location can be passed as a argument to the tool in various commands. + ++ +---- +fedora-change-wrangler auth taiga --config /disk/folder/file.ini +---- + +=== Taiga Config +The config.ini file contains a [TAIGA] section which has all the taiga related configurations in it.The file holds the ID's using which taiga maps and identifies the userstories,statuses,custom attributes,epics etc. + +Without the ID's the tool would not function thus the user should fetch and set the custom attribtue id's as per the taiga instance they are using. +More information to fetch the ID'S can be found in https://taigaio.github.io/taiga-doc/dist/api.html[Taiga Documentation] + ++ +---- +[TAIGA] +TAIGA_URL = https://teams.fedoraproject.org +---- + +=== Pagure COnfig +The config.ini file contains the [PAGURE] section which has all the pagure related configurations in it.The section holds the service ID and the repository url's. + ++ +---- +[PAGURE] +FESCO_REPO = my repo name +RELEASE NOTES REPO = I give this a name +---- + +=== Bugzilla Config +The config.ini file contains the [PAGURE] section which has all the pagure related configurations in it.The section holds the service ID and the repository url's. + ++ +---- +[BUGZILLA] +BUGZILLA_URL = https://bugzilla.redhat.com +---- + diff --git a/Docs/modules/ROOT/pages/Config/config-note.adoc b/Docs/modules/ROOT/pages/Config/config-note.adoc new file mode 100644 index 0000000..32289f4 --- /dev/null +++ b/Docs/modules/ROOT/pages/Config/config-note.adoc @@ -0,0 +1,4 @@ +[NOTE] +==== +The --config is a optional command.If not passed it defaults to using the config.ini file from the the repo itself +==== diff --git a/Docs/modules/ROOT/pages/Convert/convert.adoc b/Docs/modules/ROOT/pages/Convert/convert.adoc new file mode 100644 index 0000000..e2d1a25 --- /dev/null +++ b/Docs/modules/ROOT/pages/Convert/convert.adoc @@ -0,0 +1,29 @@ +ifdef::context[:parent-context: {context}] +:context: convert + += Convert + +Note : The convert functionality is bundled in the accept functionality,indivisual conversion without the accept functionality is still possible. + +The convert command converts the issues in to Userstories on taiga. The user can spcify any no of issues to convert at once.The convert functionality not only creates the userstory but also maps all the custom attribtues of the issue to the user stoy. Once the issue is succcesuflly converted to the user story,the issue status is changed to close/processed. + +include::config.note.adoc[] + + +== Single Conversion + +Single Issue conversion example shown below,the "X" is the issue refrence no(the issue no that is seen in the gui) from taiga. + ++ +---- +fedora-change-wrangler convert --taiga "X" +---- + +== Bulk Conversion + +Bulk conversion example is shown below, the "X" is the issue refrence no(the issue no is seen in the gui). Multiple issues can thus be converted at once. + ++ +---- +fedora-change-wrangler convert --taiga 25 30 45 50 +---- diff --git a/Docs/modules/ROOT/pages/Developer Documentation/Bugzilla/Bugzilla-dev.adoc b/Docs/modules/ROOT/pages/Developer Documentation/Bugzilla/Bugzilla-dev.adoc new file mode 100644 index 0000000..01571d0 --- /dev/null +++ b/Docs/modules/ROOT/pages/Developer Documentation/Bugzilla/Bugzilla-dev.adoc @@ -0,0 +1,6 @@ +ifdef::context[:parent-context: {context}] +:context: bugzilla-dev.adoc + +The Current version of the Tool uses the https://github.com/python-bugzilla/python-bugzilla[Python-Bugzilla] to interact with bugzilla as there were too many issues with bugzillas rest api. + +One may find more information on the tool at the above link. diff --git a/Docs/modules/ROOT/pages/Developer Documentation/Config/config-dev.adoc b/Docs/modules/ROOT/pages/Developer Documentation/Config/config-dev.adoc new file mode 100644 index 0000000..38089b1 --- /dev/null +++ b/Docs/modules/ROOT/pages/Developer Documentation/Config/config-dev.adoc @@ -0,0 +1,6 @@ +ifdef::context[:parent-context: {context}] +:context: config-dev.adoc + +The config file is in a .ini format as it is human readable unlike json,yaml and similar ones. + +The config file can also be supplied from a user defined location usng the --config flag.The config contains all the required details mostly for taiga as the id's are important. diff --git a/Docs/modules/ROOT/pages/Developer Documentation/Mailing/mailing-list.adoc b/Docs/modules/ROOT/pages/Developer Documentation/Mailing/mailing-list.adoc new file mode 100644 index 0000000..b5c649c --- /dev/null +++ b/Docs/modules/ROOT/pages/Developer Documentation/Mailing/mailing-list.adoc @@ -0,0 +1,7 @@ +ifdef::context[:parent-context: {context}] +:context: mailing-list.adoc + +The Mailing functionality uses SMTP Multipart.The --reply flag if given in the cli sets the header to reply all to gain this we use a combination of lists and Multipart reply to header. + +Note: +By defualt wihtout the --reply flag the first id in the config.ini senders list is set in the reply to header and reply to all defaults to just that adress. diff --git a/Docs/modules/ROOT/pages/Developer Documentation/Pagure/pagure-dev.adoc b/Docs/modules/ROOT/pages/Developer Documentation/Pagure/pagure-dev.adoc new file mode 100644 index 0000000..5d99007 --- /dev/null +++ b/Docs/modules/ROOT/pages/Developer Documentation/Pagure/pagure-dev.adoc @@ -0,0 +1,11 @@ +ifdef::context[:parent-context: {context}] +:context: pagure-dev.adoc + +=== Auth +As mentioned in the user docs the api keys per repo are stored securly,they keyring module is used for the store of all the keys mapped by their repo name.Due to certain limitation only the fesco and the release docs keys are stored instead of per repo storage which was in a early commit of the tool. + +The authorization:token format is used and the tokens/api keys are passed in the header + +=== Calls & Token +All the calls are done via the rest api of pagure and use the requests module to call them. + diff --git a/Docs/modules/ROOT/pages/Developer Documentation/Taiga/taiga-dev.adoc b/Docs/modules/ROOT/pages/Developer Documentation/Taiga/taiga-dev.adoc new file mode 100644 index 0000000..666d14b --- /dev/null +++ b/Docs/modules/ROOT/pages/Developer Documentation/Taiga/taiga-dev.adoc @@ -0,0 +1,19 @@ +ifdef::context[:parent-context: {context}] +:context: taiga.adoc + +=== Auth +Taiga uses a token based auth each request to the api needs the token to be able to function.The token is fetching using the user id and password and then via https://taigaio.github.io/taiga-doc/dist/api.html#auth-normal-login[another call] the token is retrived and stored in the keyring. + +=== Conversion +Since there exists no endpoint for the direct conversion of the issue to user story,it has to be done manually. +1. Fetch the issue with its refrence id. +2. Fetch the Issues custom attributes using the issue id fetched from Step 1. +3. Post the User Story with the issue description retrived using Step 1 +4. Post the User Story Custom Attributes Fetched using Step 2. +5. Map the User Story as per the version custom attribute fetched from Step 2 to the respective Epic. +6. Changed the Issue Status to Closed. + +=== Config Mappings +Since taiga uses the ID format to recognize each function,custom attribute and issue the config file contains all the id's for the specifc status's,custom attributes etc + +Without these config mappings everything would have to be hardcoded which removes the functionality of having it point to user specific taiga instance. diff --git a/Docs/modules/ROOT/pages/Fesco/fesco.adoc b/Docs/modules/ROOT/pages/Fesco/fesco.adoc new file mode 100644 index 0000000..3c1d602 --- /dev/null +++ b/Docs/modules/ROOT/pages/Fesco/fesco.adoc @@ -0,0 +1,23 @@ +ifdef::context[:parent-context: {context}] +:context: fesco + += Fesco +The fesco command is used to create a issue with all the details of the proposed change and the link to the issue in taiga.The actual fesco repo can be pointed and changed via the config.ini file. + +include::config.note.adoc[] + +=== Create a issue +To create a issue the following command would be required below,the "X" is the issue refrence no(the issue no that is seen in the gui) from taiga. + ++ +---- +fedora-change-wrangler fesco --fesco "X" +---- + +=== Bulk Creation +To create issue in bulk ,below,the "X" is the issue refrence no(the issue no that is seen in the gui) from taiga. + ++ +--- +fedora-change-wrangler fesco --fesco 10 20 30 40 50 +--- diff --git a/Docs/modules/ROOT/pages/List/List-Userstories b/Docs/modules/ROOT/pages/List/List-Userstories new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/Docs/modules/ROOT/pages/List/List-Userstories diff --git a/Docs/modules/ROOT/pages/List/list.adoc b/Docs/modules/ROOT/pages/List/list.adoc new file mode 100644 index 0000000..8eb9a6b --- /dev/null +++ b/Docs/modules/ROOT/pages/List/list.adoc @@ -0,0 +1,22 @@ +ifdef::context[:parent-context: {context}] +:context: list-userstories + += List +Listing is a functionality that allows the User to List out all the pending Usestories and Issues,It is configered to list all the Userstories and issues with the new status. + +List command prints out the output in the console itslef using ASCII formating and tables for good visuals. +The user would be able to see the version no,the subject and the issue no. + +=== List Issues + +To list Issue : ++ +---- +fedora-change-wrangeler list issue --pending +---- + +=== List UserStories : ++ +---- +fedora-change-wrangeler list Userstories -- pending +---- diff --git a/Docs/modules/ROOT/pages/Sync/sync-status.adoc b/Docs/modules/ROOT/pages/Sync/sync-status.adoc new file mode 100644 index 0000000..641eee9 --- /dev/null +++ b/Docs/modules/ROOT/pages/Sync/sync-status.adoc @@ -0,0 +1,17 @@ +ifdef::context[:parent-context: {context}] +:context: sync-status + += Sync +Sync-Status command would allow the user to sync the status of the bz to the status of taiga. It fetches the status from bugzilla and updates the appropriate one on the user story in taiga. +If the Bugzilla status is Modifies then the taiga user story status would be update to Testable +If the Bugzilla status is ON_QA then the Taiga user story status would update to Code_Complete + +The Sync command takes the fedora version as a argument which is linked to the epics for more on that you can refer to the link_here[Developer Documentation]. + +=== Sync-Status Bugzilla to Taiga + +To sync in the cli the following command has to be used with 32 being the fedora change version it is intended for : ++ +---- +fedora-change-wrangler sync-status 32 +---- diff --git a/Docs/preview.sh b/Docs/preview.sh new file mode 100644 index 0000000..effb9bd --- /dev/null +++ b/Docs/preview.sh @@ -0,0 +1,35 @@ + +#!/bin/sh + + +if [ "$(uname)" == "Darwin" ]; then + + # Running on macOS. + + # Let's assume that the user has the Docker CE installed + + # which doesn't require a root password. + + echo "The preview will be available at http://localhost:8080/" + + docker run --rm -v $(pwd):/antora:ro -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro -p 8080:80 nginx + + + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + + # Running on Linux. + + # Fedora Workstation has python3 installed as a default, so using that + + echo "" + + echo "The preview is available at http://localhost:8080" + + echo "" + + cd ./public + + python3 -m http.server 8080 + +fi \ No newline at end of file diff --git a/Docs/site.yml b/Docs/site.yml new file mode 100644 index 0000000..483da12 --- /dev/null +++ b/Docs/site.yml @@ -0,0 +1,40 @@ + +site: + + title: Fedora Change Wrangler Usage Guide + + start_page: fedora-change-wrangler::index + +content: + + sources: + + - url: . + + branches: HEAD + +ui: + + bundle: + + url: https://asamalik.fedorapeople.org/ui-bundle.zip + + snapshot: true + + default_layout: with_menu + +output: + + clean: true + + dir: ./public + + destinations: + + - provider: archive + +runtime: + + pull: true + + cache_dir: ./cache \ No newline at end of file