# **ColMiner**
O projeto ColMiner tem como objetivo analisar dados de ambientes de issue tracking com o intuito de apoiar o gerenciamento das comunicações em projetos de software. Para isso, a principal métrica utilizada nas análises é a relevância temática dos comentários postados nas issues associada a outras medidas quantitativas que possam revelar possíveis falhas de comunicação.
<br>
## **Sobre a biblioteca RIT**
A biblioteca RIT (Relevance in Issue Tracking) faz parte dos refinamentos e extensões da ferramenta ColMiner, em que suas macro-funcionalidades serão modularizadas e estendidas. Essa biblioteca analisa os comentários postados no ambiente de issue tracking do GitHub, por meio do cálculo da Relevância Temática dos mesmos, ou seja, calcula-se quão relevantes os comentários são para uma discussão. Através da biblioteca RIT, é possível:
<br>
* Calcular o quão relevante é cada comentário para o tema da discussão de uma _issue_ no GitHub;
* Exportar os dados relacionados as _issues_ junto com a relevência temática dos comentários através do formato CSV.
<br>
## **Pré-requisitos**
Para utilizar a biblioteca basta ter instalado na sua máquina:
* [Python](https://www.python.org/downloads/)
* [Git](https://github.com/git-guides/install-git)
* [PIP](https://www.makeuseof.com/tag/install-pip-for-python/)
## **Instalação e uso**
Siga as etapas abaixo para utilizar a biblioteca RIT:
1) Na pasta raíz do seu projeto clone este repositório com o comando:
```
git clone https://github.com/BibliotecaRIT/BibliotecaRIT.git
```
2) Após a etapa acima execute o seguinte comando para instalar as dependências da biblioteca:
```
pip install -r BibliotecaRIT/requirements.txt
```
3) Para realizar as requisições é necessário inserir um [_personal access token_](https://docs.github.com/pt/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). Para utilizar a sua chave, crie um arquivo chamado _.env_ e utilize o modelo disponibilizado no arquivo _.env.example_, colocando a sua chave no lugar indicado. **O token deve estar dentro do arquivo _.env_ da mesma forma que está no arquivo _.env.example_**.
Exemplo:
```
TOKEN = "ghp..."
```
4) Por fim, importe a RIT no seu arquivo fonte desta forma:
```
from BibliotecaRIT.Sources.BibliotecaRITFachada import BibliotecaRITFachada
```
## **Método _calcularRelevanciaTematicaGitHub_**
A biblioteca dispõe de um único método a ser usado:
```
def calcularRelevanciaTematicaGitHub(self, usuario, repositorio, visao, autor , data)
```
Abaixo é descrito as informações necessárias para utilizar este método.
* No campo _usuario_ deve ser fornecido nome do dono do repositório que se deseja analisar a _issue_.
* No campo _repositorio_ deve ser fornecido o nome do repositório da _issue_ que será analisada.
* No campo _visao_ deve ser fornecido o tipo de filtro que será aplicado aos dados que serão exportados, sendo:
* 1 para filtrar por _issues_ abertas
* 2 para filtrar por _issues_ fechadas
* 3 para filtrar por _issues_ abertas e fechadas
* 4 para filtrar comentários por autor
* 5 para filtrar comentários por data
* No campo _autor_ deve ser fornecido o nome do autor que será utilizado para filtrar os comentários caso seja selecionado o filtro 4, caso contrário não precisa ser fornecido.
* No campo _data_ deve ser fornecido a data que será utilizada para filtrar os comentários caso seja selecionado o filtro 5, caso contrário não precisa ser fornecido. As datas devem ser fornecidas no formato yyyy-mm-dd.
Ao final da execução deste método é gerado um arquivos 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**
No exemplo a seguir, será mostrado 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).
```
1 from Sources.BibliotecaRITFachada import BibliotecaRITFachada
2 # Instância da biblioteca
3 rit = BibliotecaRITFachada()
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)
```
As linhas 4, 5, e 6 podem ser substituídas pelos códigos abaixo, variando com o tipo de filtro que é utilizado.
- 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)
```
- 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)
```
- 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,autor="smayas")
```
- 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,data="2021-07-15")
```
### Saída
Ao executar o exemplo acima é gerado um arquivo CSV com o nome _dotenv.csv_, o qual contém os dados relacionados as _issues_ e a relevância temática dos comentários das issues.a
Raw data
{
"_id": null,
"home_page": "https://github.com/BibliotecaRIT/BibliotecaRIT",
"name": "testeBibRit",
"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": "# **ColMiner**\n\nO projeto ColMiner tem como objetivo analisar dados de ambientes de issue tracking com o intuito de apoiar o gerenciamento das comunica\u00e7\u00f5es em projetos de software. Para isso, a principal m\u00e9trica utilizada nas an\u00e1lises \u00e9 a relev\u00e2ncia tem\u00e1tica dos coment\u00e1rios postados nas issues associada a outras medidas quantitativas que possam revelar poss\u00edveis falhas de comunica\u00e7\u00e3o.\n\n<br>\n\n## **Sobre a biblioteca RIT**\n\nA biblioteca RIT (Relevance in Issue Tracking) faz parte dos refinamentos e extens\u00f5es da ferramenta ColMiner, em que suas macro-funcionalidades ser\u00e3o modularizadas e estendidas. Essa biblioteca analisa os coment\u00e1rios postados no ambiente de issue tracking do GitHub, por meio do c\u00e1lculo da Relev\u00e2ncia Tem\u00e1tica dos mesmos, ou seja, calcula-se qu\u00e3o relevantes os coment\u00e1rios s\u00e3o para uma discuss\u00e3o. Atrav\u00e9s da biblioteca RIT, \u00e9 poss\u00edvel:\n<br>\n\n* Calcular o qu\u00e3o relevante \u00e9 cada coment\u00e1rio para o tema da discuss\u00e3o de uma _issue_ no GitHub;\n* Exportar os dados relacionados as _issues_ junto com a relev\u00eancia tem\u00e1tica dos coment\u00e1rios atrav\u00e9s do formato CSV.\n\n\n<br>\n\n## **Pr\u00e9-requisitos**\nPara utilizar a biblioteca basta ter instalado na sua m\u00e1quina:\n* [Python](https://www.python.org/downloads/) \n* [Git](https://github.com/git-guides/install-git)\n* [PIP](https://www.makeuseof.com/tag/install-pip-for-python/)\n\n\n## **Instala\u00e7\u00e3o e uso**\nSiga as etapas abaixo para utilizar a biblioteca RIT:\n\n1) Na pasta ra\u00edz do seu projeto clone este reposit\u00f3rio com o comando: \n``` \ngit clone https://github.com/BibliotecaRIT/BibliotecaRIT.git\n``` \n2) Ap\u00f3s a etapa acima execute o seguinte comando para instalar as depend\u00eancias da biblioteca:\n``` \npip install -r BibliotecaRIT/requirements.txt\n```\n3) Para realizar as requisi\u00e7\u00f5es \u00e9 necess\u00e1rio inserir um [_personal access token_](https://docs.github.com/pt/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). Para utilizar a sua chave, crie um arquivo chamado _.env_ e utilize o modelo disponibilizado no arquivo _.env.example_, colocando a sua chave no lugar indicado. **O token deve estar dentro do arquivo _.env_ da mesma forma que est\u00e1 no arquivo _.env.example_**.\nExemplo: \n```\nTOKEN = \"ghp...\"\n```\n\n4) Por fim, importe a RIT no seu arquivo fonte desta forma:\n``` \nfrom BibliotecaRIT.Sources.BibliotecaRITFachada import BibliotecaRITFachada\n```\n\n## **M\u00e9todo _calcularRelevanciaTematicaGitHub_**\nA biblioteca disp\u00f5e de um \u00fanico m\u00e9todo a ser usado:\n```\ndef calcularRelevanciaTematicaGitHub(self, usuario, repositorio, visao, autor , data)\n```\nAbaixo \u00e9 descrito as informa\u00e7\u00f5es necess\u00e1rias para utilizar este m\u00e9todo.\n* No campo _usuario_ deve ser fornecido nome do dono do reposit\u00f3rio que se deseja analisar a _issue_.\n* No campo _repositorio_ deve ser fornecido o nome do reposit\u00f3rio da _issue_ que ser\u00e1 analisada.\n* No campo _visao_ deve ser fornecido o tipo de filtro que ser\u00e1 aplicado aos dados que ser\u00e3o exportados, sendo: \n * 1 para filtrar por _issues_ abertas\n * 2 para filtrar por _issues_ fechadas\n * 3 para filtrar por _issues_ abertas e fechadas\n * 4 para filtrar coment\u00e1rios por autor\n * 5 para filtrar coment\u00e1rios por data\n* No campo _autor_ deve ser fornecido o nome do autor que ser\u00e1 utilizado para filtrar os coment\u00e1rios caso seja selecionado o filtro 4, caso contr\u00e1rio n\u00e3o precisa ser fornecido.\n* No campo _data_ deve ser fornecido a data que ser\u00e1 utilizada para filtrar os coment\u00e1rios caso seja selecionado o filtro 5, caso contr\u00e1rio n\u00e3o precisa ser fornecido. As datas devem ser fornecidas no formato yyyy-mm-dd.\n\nAo final da execu\u00e7\u00e3o deste m\u00e9todo \u00e9 gerado um arquivos 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**\nNo exemplo a seguir, ser\u00e1 mostrado 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```\n1 from Sources.BibliotecaRITFachada import BibliotecaRITFachada\n2 # Inst\u00e2ncia da biblioteca\n3 rit = BibliotecaRITFachada()\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```\nAs linhas 4, 5, e 6 podem ser substitu\u00eddas pelos c\u00f3digos abaixo, variando com o tipo de filtro que \u00e9 utilizado.\n\n- 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- 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- 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\u00e9m somente coment\u00e1rios do autor smayas\n6 rit.calcularRelevanciaTematicaGitHub(usuario=\"mockturtl\",repositorio=\"dotenv\",visao=4,autor=\"smayas\")\n```\n- 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\u00e9m somente coment\u00e1rios na data 15/07/2021\n6 rit.calcularRelevanciaTematicaGitHub(usuario=\"mockturtl\",repositorio=\"dotenv\",visao=5,data=\"2021-07-15\")\n```\n### Sa\u00edda\nAo executar o exemplo acima \u00e9 gerado um arquivo CSV com o nome _dotenv.csv_, o qual cont\u00e9m os dados relacionados as _issues_ e a relev\u00e2ncia tem\u00e1tica dos coment\u00e1rios das issues.a\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "",
"version": "1.0.0",
"split_keywords": [
"relev\u00e2ncia tem\u00e1tica",
"issue tracking",
"similaridade de cossenos"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "449a40dbdea40731dfdea6a4df649fd028e55f066d32d8312390aab4ea1704a9",
"md5": "fc329808ea86c97e1aef32933f8b0182",
"sha256": "ae93c72ed61035f222724db9ab17769632ee3a9cc2526cfa97e64bdf8bc11c1d"
},
"downloads": -1,
"filename": "testeBibRit-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc329808ea86c97e1aef32933f8b0182",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11322,
"upload_time": "2023-01-03T16:11:31",
"upload_time_iso_8601": "2023-01-03T16:11:31.042342Z",
"url": "https://files.pythonhosted.org/packages/44/9a/40dbdea40731dfdea6a4df649fd028e55f066d32d8312390aab4ea1704a9/testeBibRit-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-03 16:11:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "BibliotecaRIT",
"github_project": "BibliotecaRIT",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "stackapi",
"specs": []
}
],
"lcname": "testebibrit"
}
JSON
