## Sobre a Biblioteca RIT
A biblioteca RIT (Relevance in Issue Tracking) analisa os comentários postados no ambiente de issue tracking do GitHub, por meio do cálculo da métrica de Relevância Temática dos mesmos. Essa métrica calcula quão relevantes os comentários são para uma discussão no contexto da issue (inclui pull requests por serem um tipo “especial” de issue). Os dados das issues com as respectivas relevâncias dos comentários são exportados em formato CSV, por meio de visões pré-selecionadas pela aplicação cliente.
A biblioteca RIT faz parte dos esforços de modularização da ferramenta [Colminer](http://nupessc.caf.ufv.br/#/nupessc/projetos/colminer), sendo responsável, exclusivamente, pelo cálculo da principal métrica utilizada pela ferramenta, a relevância temática.
## Pré-requisitos
Para utilizar a biblioteca, basta ter instalado na sua máquina:
* [Python >= 3.10](https://www.python.org/downloads/)
* [PIP >= 22.3](https://www.makeuseof.com/tag/install-pip-for-python/)
## Instalação
Para instalar a biblioteca execute o comando:
No linux:
```
pip3 install Biblioteca-RIT
```
No Windows:
```
pip install Biblioteca-RIT
```
## Uso
1) Para que a biblioteca possa fazer as requisições no GitHub é necessário criar um [_personal access token_](https://docs.github.com/pt/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
- Caso a biblioteca seja utilizada para calcular a relevância temática de um grande volume de dados, é recomendado fornecer mais de um token.
2) Importe a biblioteca RIT no seu arquivo fonte:
```
from BibliotecaRIT.BibliotecaRITFachada import BibliotecaRITFachada
```
3) Instancie a biblioteca fornecendo os seus tokens, exemplo:
```
rit = BibliotecaRITFachada(tokens=[“token1”,”token2”,”token3”])
```
## Método calcularRelevanciaTematicaGitHub
A biblioteca dispõe de um único método a ser usado:
```
def calcularRelevanciaTematicaGitHub(self, usuario, repositorio, visao, arg, pagInicial)
```
Abaixo são descritas as informações necessárias para utilizar este método.
No campo _usuario_, insira o nome do dono do repositório a ser analisado.
No campo _repositorio_, insira o nome do repositório a ser analisado.
No campo _visao_, selecione o tipo de filtro que será aplicado às _ issues _ do repositórios especificados, sendo:
* 1 para filtrar por comentários de _issues_ abertas
* 2 para filtrar por comentários de _issues_ fechadas
* 3 para filtrar por comentários de _issues_ abertas e fechadas
Caso não seja especificada nenhuma visão, esta será utilizada.
* 4 para filtrar comentários por autor, tanto para issues abertas quanto fechadas
* 5 para filtrar comentários por data, para issues abertas e fechadas
No campo _arg_, deve ser fornecido o nome do autor (usuário correspondente), no caso de ser selecionado o filtro 4 OU a data, caso o filtro 5 tenha sido escolhido. Caso contrário, não é necessário utilizá-lo.
* O campo _pagInicial_ deve ser utilizado quando ocorrer algum erro durante a extração dos dados, como por exemplo, não forem extraídos os dados de todas as _issues_ do repositório por não possuir tokens suficientes ou erro de conexão com a internet. Assim, é possível reaproveitar os dados já extraídos e começar novamente o cálculo de relevância temática a partir da página de _issues_ que gerou erro. Por padrão, este campo possui valor 1, indicando que o cálculo de relevância será realizado a partir da primeira página.
Ao final da execução do método calcularRelevanciaTematicaGitHub(...), é gerado um arquivo CSV que contém os seguintes dados acerca das _issues_ e seus comentários: ID da _issue_, título da _issue_, descrição da _issue_, data de criação da issue, ID do comentário, comentário, data do comentário, Relevância Temática dos comentários e nome do autor do comentário.
## Exemplo de uso
No exemplo a seguir, ilustra-se como utilizar a biblioteca RIT para calcular a relevância temática dos comentários do seguinte repositório: [https://github.com/mockturtl/dotenv](https://github.com/mockturtl/dotenv).
### Instância da biblioteca
```
1 from BibliotecaRIT.BibliotecaRITFachada import BibliotecaRITFachada
2 # Instância da biblioteca
3 rit = BibliotecaRITFachada(tokens=[“ghp…”])
````
- Utilizando o filtro 1
```
4 # Extrai e exporta em um arquivo CSV, dados sobre as issues abertas do repositório dotenv do usuário mockturtl
5 # com a relevância temática dos comentários
6 rit.calcularRelevanciaTematicaGitHub(usuario="mockturtl",repositorio="dotenv",visao=1)
```
- Utilizando o filtro 2
```
4 # Extrai e exporta em um arquivo CSV, dados sobre as issues fechadas do repositório dotenv do usuário mockturtl
5 # com a relevância temática dos comentários
6 rit.calcularRelevanciaTematicaGitHub(usuario="mockturtl",repositorio="dotenv",visao=2)
```
- Utilizando o filtro 3
```
4 # Extrai e exporta em um arquivo CSV, dados sobre as issues abertas e fechadas do repositório dotenv do usuário mockturtl
5 # com a relevância temática dos comentários
6 rit.calcularRelevanciaTematicaGitHub(usuario="mockturtl",repositorio="dotenv",visao=3)
```
- Utilizando o filtro 4
```
4 # Extrai e exporta em um arquivo CSV, dados sobre as issues abertas e fechadas do repositório dotenv do usuário mockturtl
5 # com a relevância temática dos comentários que contêm somente comentários do autor smayas
6 rit.calcularRelevanciaTematicaGitHub(usuario="mockturtl",repositorio="dotenv",visao=4,arg="smayas")
```
- Utilizando o filtro 5
```
4 # Extrai e exporta em um arquivo CSV, dados sobre as issues abertas e fechadas do repositório dotenv do usuário mockturtl
5 # com a relevância temática dos comentários que contêm somente comentários na data 15/07/2021
6 rit.calcularRelevanciaTematicaGitHub(usuario="mockturtl",repositorio="dotenv",visao=5,arg="2021-07-15")
```
### Saída
Ao executar algum dos exemplos acima, são gerados dois arquivos CSVs com os nomes _dotenv-comentarios-x.csv_ e _dotenv-issues-x_, onde x é número da visão que foi escolhida. Estes arquivos contém, respectivamente, os dados acerca dos comentários e das _issues_ do repositório dotenv.
Raw data
{
"_id": null,
"home_page": "https://github.com/BibliotecaRIT/BibliotecaRIT",
"name": "Biblioteca-RIT",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "relev\u00e2ncia tem\u00e1tica,issue tracking,similaridade de cossenos",
"author": "NuPESSC",
"author_email": "nupessc@ufv.br",
"download_url": "",
"platform": null,
"description": "## Sobre a Biblioteca RIT\n\nA biblioteca RIT (Relevance in Issue Tracking) analisa os coment\u00e1rios postados no ambiente de issue tracking do GitHub, por meio do c\u00e1lculo da m\u00e9trica de Relev\u00e2ncia Tem\u00e1tica dos mesmos. Essa m\u00e9trica calcula qu\u00e3o relevantes os coment\u00e1rios s\u00e3o para uma discuss\u00e3o no contexto da issue (inclui pull requests por serem um tipo \u201cespecial\u201d de issue). Os dados das issues com as respectivas relev\u00e2ncias dos coment\u00e1rios s\u00e3o exportados em formato CSV, por meio de vis\u00f5es pr\u00e9-selecionadas pela aplica\u00e7\u00e3o cliente. \n\nA biblioteca RIT faz parte dos esfor\u00e7os de modulariza\u00e7\u00e3o da ferramenta [Colminer](http://nupessc.caf.ufv.br/#/nupessc/projetos/colminer), sendo respons\u00e1vel, exclusivamente, pelo c\u00e1lculo da principal m\u00e9trica utilizada pela ferramenta, a relev\u00e2ncia tem\u00e1tica.\n\n## Pr\u00e9-requisitos\nPara utilizar a biblioteca, basta ter instalado na sua m\u00e1quina:\n* [Python >= 3.10](https://www.python.org/downloads/)\n* [PIP >= 22.3](https://www.makeuseof.com/tag/install-pip-for-python/)\n\n## Instala\u00e7\u00e3o\nPara instalar a biblioteca execute o comando:\n\nNo linux:\n\n``` \npip3 install Biblioteca-RIT\n```\n\nNo Windows:\n``` \npip install Biblioteca-RIT\n```\n## Uso\n1) Para que a biblioteca possa fazer as requisi\u00e7\u00f5es no GitHub \u00e9 necess\u00e1rio criar um [_personal access token_](https://docs.github.com/pt/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).\n - Caso a biblioteca seja utilizada para calcular a relev\u00e2ncia tem\u00e1tica de um grande volume de dados, \u00e9 recomendado fornecer mais de um token.\n\n2) Importe a biblioteca RIT no seu arquivo fonte:\n``` \nfrom BibliotecaRIT.BibliotecaRITFachada import BibliotecaRITFachada\n```\n3) Instancie a biblioteca fornecendo os seus tokens, exemplo:\n``` \nrit = BibliotecaRITFachada(tokens=[\u201ctoken1\u201d,\u201dtoken2\u201d,\u201dtoken3\u201d])\n```\n## M\u00e9todo calcularRelevanciaTematicaGitHub\nA biblioteca disp\u00f5e de um \u00fanico m\u00e9todo a ser usado:\n```\ndef calcularRelevanciaTematicaGitHub(self, usuario, repositorio, visao, arg, pagInicial)\n```\nAbaixo s\u00e3o descritas as informa\u00e7\u00f5es necess\u00e1rias para utilizar este m\u00e9todo.\n No campo _usuario_, insira o nome do dono do reposit\u00f3rio a ser analisado.\n No campo _repositorio_, insira o nome do reposit\u00f3rio a ser analisado.\n No campo _visao_, selecione o tipo de filtro que ser\u00e1 aplicado \u00e0s _ issues _ do reposit\u00f3rios especificados, sendo: \n* 1 para filtrar por coment\u00e1rios de _issues_ abertas\n* 2 para filtrar por coment\u00e1rios de _issues_ fechadas\n* 3 para filtrar por coment\u00e1rios de _issues_ abertas e fechadas\nCaso n\u00e3o seja especificada nenhuma vis\u00e3o, esta ser\u00e1 utilizada.\n* 4 para filtrar coment\u00e1rios por autor, tanto para issues abertas quanto fechadas\n* 5 para filtrar coment\u00e1rios por data, para issues abertas e fechadas\nNo campo _arg_, deve ser fornecido o nome do autor (usu\u00e1rio correspondente), no caso de ser selecionado o filtro 4 OU a data, caso o filtro 5 tenha sido escolhido. Caso contr\u00e1rio, n\u00e3o \u00e9 necess\u00e1rio utiliz\u00e1-lo.\n* O campo _pagInicial_ deve ser utilizado quando ocorrer algum erro durante a extra\u00e7\u00e3o dos dados, como por exemplo, n\u00e3o forem extra\u00eddos os dados de todas as _issues_ do reposit\u00f3rio por n\u00e3o possuir tokens suficientes ou erro de conex\u00e3o com a internet. Assim, \u00e9 poss\u00edvel reaproveitar os dados j\u00e1 extra\u00eddos e come\u00e7ar novamente o c\u00e1lculo de relev\u00e2ncia tem\u00e1tica a partir da p\u00e1gina de _issues_ que gerou erro. Por padr\u00e3o, este campo possui valor 1, indicando que o c\u00e1lculo de relev\u00e2ncia ser\u00e1 realizado a partir da primeira p\u00e1gina.\n\nAo final da execu\u00e7\u00e3o do m\u00e9todo calcularRelevanciaTematicaGitHub(...), \u00e9 gerado um arquivo CSV que cont\u00e9m os seguintes dados acerca das _issues_ e seus coment\u00e1rios: ID da _issue_, t\u00edtulo da _issue_, descri\u00e7\u00e3o da _issue_, data de cria\u00e7\u00e3o da issue, ID do coment\u00e1rio, coment\u00e1rio, data do coment\u00e1rio, Relev\u00e2ncia Tem\u00e1tica dos coment\u00e1rios e nome do autor do coment\u00e1rio.\n\n## Exemplo de uso\nNo exemplo a seguir, ilustra-se como utilizar a biblioteca RIT para calcular a relev\u00e2ncia tem\u00e1tica dos coment\u00e1rios do seguinte reposit\u00f3rio: [https://github.com/mockturtl/dotenv](https://github.com/mockturtl/dotenv).\n\n### Inst\u00e2ncia da biblioteca\n\n```\n1 from BibliotecaRIT.BibliotecaRITFachada import BibliotecaRITFachada\n2 # Inst\u00e2ncia da biblioteca\n3 rit = BibliotecaRITFachada(tokens=[\u201cghp\u2026\u201d])\n````\n- Utilizando o filtro 1\n\n```\n4 # Extrai e exporta em um arquivo CSV, dados sobre as issues abertas do reposit\u00f3rio dotenv do usu\u00e1rio mockturtl\n5 # com a relev\u00e2ncia tem\u00e1tica dos coment\u00e1rios\n6 rit.calcularRelevanciaTematicaGitHub(usuario=\"mockturtl\",repositorio=\"dotenv\",visao=1)\n```\n\n- Utilizando o filtro 2\n```\n4 # Extrai e exporta em um arquivo CSV, dados sobre as issues fechadas do reposit\u00f3rio dotenv do usu\u00e1rio mockturtl\n5 # com a relev\u00e2ncia tem\u00e1tica dos coment\u00e1rios\n6 rit.calcularRelevanciaTematicaGitHub(usuario=\"mockturtl\",repositorio=\"dotenv\",visao=2)\n``` \n- Utilizando o filtro 3\n```\n4 # Extrai e exporta em um arquivo CSV, dados sobre as issues abertas e fechadas do reposit\u00f3rio dotenv do usu\u00e1rio mockturtl\n5 # com a relev\u00e2ncia tem\u00e1tica dos coment\u00e1rios\n6 rit.calcularRelevanciaTematicaGitHub(usuario=\"mockturtl\",repositorio=\"dotenv\",visao=3)\n``` \n- Utilizando o filtro 4\n```\n4 # Extrai e exporta em um arquivo CSV, dados sobre as issues abertas e fechadas do reposit\u00f3rio dotenv do usu\u00e1rio mockturtl \n5 # com a relev\u00e2ncia tem\u00e1tica dos coment\u00e1rios que cont\u00eam somente coment\u00e1rios do autor smayas\n6 rit.calcularRelevanciaTematicaGitHub(usuario=\"mockturtl\",repositorio=\"dotenv\",visao=4,arg=\"smayas\")\n```\n- Utilizando o filtro 5\n```\n4 # Extrai e exporta em um arquivo CSV, dados sobre as issues abertas e fechadas do reposit\u00f3rio dotenv do usu\u00e1rio mockturtl\n5 # com a relev\u00e2ncia tem\u00e1tica dos coment\u00e1rios que cont\u00eam somente coment\u00e1rios na data 15/07/2021\n6 rit.calcularRelevanciaTematicaGitHub(usuario=\"mockturtl\",repositorio=\"dotenv\",visao=5,arg=\"2021-07-15\")\n``` \n### Sa\u00edda\nAo executar algum dos exemplos acima, s\u00e3o gerados dois arquivos CSVs com os nomes _dotenv-comentarios-x.csv_ e _dotenv-issues-x_, onde x \u00e9 n\u00famero da vis\u00e3o que foi escolhida. Estes arquivos cont\u00e9m, respectivamente, os dados acerca dos coment\u00e1rios e das _issues_ do reposit\u00f3rio dotenv.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/BibliotecaRIT/BibliotecaRIT"
},
"split_keywords": [
"relev\u00e2ncia tem\u00e1tica",
"issue tracking",
"similaridade de cossenos"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dba9be47d5c6d398899f0e99851af9b4c03d92bc2ebddafc0bb6a4bead1a52f0",
"md5": "0fb5c3c69013a6db1a2408858cb73538",
"sha256": "70e7e59a020fe677d48bfed4045d8035439ae0e97047c08d4de7f2fd0b79ee0a"
},
"downloads": -1,
"filename": "Biblioteca_RIT-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0fb5c3c69013a6db1a2408858cb73538",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 39089,
"upload_time": "2023-08-24T16:59:09",
"upload_time_iso_8601": "2023-08-24T16:59:09.289779Z",
"url": "https://files.pythonhosted.org/packages/db/a9/be47d5c6d398899f0e99851af9b4c03d92bc2ebddafc0bb6a4bead1a52f0/Biblioteca_RIT-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-24 16:59:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BibliotecaRIT",
"github_project": "BibliotecaRIT",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "biblioteca-rit"
}
JSON
