Skip to content

Commit

Permalink
Merge pull request #113 from mediumroast/v0.7_competitive_similarity
Browse files Browse the repository at this point in the history
V0.7 competitive similarity
  • Loading branch information
miha42-github authored Sep 5, 2024
2 parents 2ae428a + 6b8ea2d commit 5acff49
Show file tree
Hide file tree
Showing 44 changed files with 4,419 additions and 3,932 deletions.
5 changes: 3 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
node_modules/
.DS_Store
*.py
test.js
test*.*
companies.json
*.pdf
sample_pdf/
sample_pdf/
foo*.*
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
## Welcome to Open Source Mediumroast for GitHub.
Products organizations must build robust product plans from competitive and customer interactions everyone can see, use, and reference. Therefore, Mediumroast for GitHub intends to help Products oranizations construct an active interactions repository close to the action of development and issue management in GitHub.

**Notice:** You can review the [GitHub Page Version](https://mediumroast.github.io/mediumroast_js/) rather than the repository version of this documentation, but the screencasts of several of the CLI tutorials will not display.
### Notices
- A new version of the CLI is available and documentation is in progress. The major focus of this version is to add in Competitive Similarity Analysis, Interaction summarization and Interaction Proto-requirements discovery.
- You can review the [GitHub Page Version](https://mediumroast.github.io/mediumroast_js/) rather than the repository version of this documentation, but the screencasts of several of the CLI tutorials will not display.

## Installation and configuration
Mediumroast for GitHub includes a [GitHub Application](https://github.com/apps/mediumroast-for-github), a Command Line Interface, and a Software Development Kit. The following steps show you how to install the App and the CLI with SDK.

### Preinstallation requirements
1. A GitHub organization, please
1. A GitHub organization
2. Permissions in your GitHub organization to install a GitHub application.
3. Access to a command line terminal on Linux or MacOS.
4. [Node.js installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm#using-a-node-installer-to-install-nodejs-and-npm), ideally globally for all users.
Expand Down Expand Up @@ -36,7 +38,7 @@ Coming soon.
Before you can use the Mediumroast for GitHub [CLI](https://github.com/mediumroast/mediumroast_js/blob/main/cli/README.md) the environment must be setup. With the CLI installed please run `mrcli setup` to start the setup process, note there's a video of the setup process in CLI README.

## What's provided
Running `mrcli setup` creates a repository in your oganization called `<organization_name>_discovery` for all interactions and objects, creates two intitial companies, and installs two GitHub Actions to control the number of branches and provide some basic out of the box reporting -- see example screenshot below.
Running `mrcli setup` creates a repository in your oganization called `<organization_name>_discovery` to contain all interactions and companies, creates two intitial companies, and installs two GitHub Actions to control the number of branches and provide some basic out of the box reporting -- see example screenshot below.

### Warning
Since Mediumroast for GitHub creates a regular repository you can interact with it as normal, but **doing so is not recommended**. If you interact with the repository, in regular ways, this could result in Mediumroast for GitHub becoming inoperable. There are cases where it may become necessary to directly work with the repository, but that should be rare.
Expand Down
13 changes: 12 additions & 1 deletion cli/Company.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
## Companies
Company objects are central to Mediumroast for GitHub. Interaction sand in the future Studies rely on Companies to function. After setup is run, via `mrcli setup`, two companies are present to work with. Additional Companies can be added, updated, or removed; essentially, `company` is an `mrcli` sub-command that affords users Create, Read, Update and Delete capabilities. Each of the major functions for `mrcli company` are described in this document.
Company objects are central to Mediumroast for GitHub. Interactions and in the future Studies rely on Companies to function. After setup is run, via `mrcli setup`, two companies are present to work with. Additional Companies can be added, updated, or removed; essentially, `company` is an `mrcli` sub-command that affords users Create, Read, Update and Delete capabilities. Each of the major functions for `mrcli company` are described in this document.

### Notice
Some of the command line options and switches may not yet be implemented; therefore, if a switch or option is not yet implemented the CLI will inform the user and then exit.
Expand Down Expand Up @@ -100,6 +100,17 @@ A command line prompt based wizard steps the user through either a semi-automate

<img width="1178" alt="companies_add" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/d948fce2-6c31-4537-983d-9dad4c04c248">

## Report on a company
Produce a MS Word document report on a company. The report includes a dashboard with a company similarity report, company firmographics, detail on similar companies, and summaries for all interactions associated to the company reported on. The report is stored in the `$HOME/Documents` directory as `<company_name>.docx`.

Optionally, if the `--package` switch is used the report is zipped and stored in the $HOME/Documents directory as `<company_name>.zip` including all of the interactions associated to the company and the set of most and least similar companies.

### Command(s) run
- `mrcli c --report="Atlassian Corp"`
- `mrcli c --report="Atlassian Corp" --package`

### Screenshot of the report dashboard

![Screenshot 2024-09-03 at 8 23 29 AM](https://github.com/user-attachments/assets/bd1141cc-53c6-4cac-8e56-ed50601dcbb6)


9 changes: 9 additions & 0 deletions cli/Interaction.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,8 +110,17 @@ A command line prompt based wizard steps the user through a semi-automated proce

https://github.com/mediumroast/mediumroast_js/assets/10818650/0b28db90-d6ba-4224-a9ae-4c301c2b9614

## Report on an interaction
Produce a MS Word document report on an interaction. The report includes a dashboard with interaction metadata, interaction abstract, and proto-requirements. The report is stored in the `$HOME/Documents` directory as `<interaction_name>.docx`.

Optionally, if the `--package` switch is used the report is zipped and stored in the $`HOME/Documents` directory as `<interaction_name>.zip` including the interaction content.

### Command(s) run
- `mrcli i --report="Atlassian Corp"`
- `mrcli i --report="Atlassian Corp" --package`

### Screenshot of the report dashboard
![Screenshot 2024-09-04 at 8 30 25 PM](https://github.com/user-attachments/assets/19c614a5-ed58-4687-aff8-a619ea693398)



Expand Down
56 changes: 47 additions & 9 deletions cli/README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,44 @@
# Mediumroast for GitHub CLI (Command Line Interface)
The CLI is divided into two sets one for administrative interactions with the system and another for interacting with **Mediumroast for GitHub** objects like Companies and Interactions. This document covers both the administrative CLI and makes reference to the CLI set for **Mediumroast for GitHub** objects.

# Authentication
**Mediumroast for GitHub** uses either Device Flow or a Personal Access Token for authentication. The setup CLI will prompt you to choose the type of authentication and then store the necessary information in the `${HOME}/.mediumroast/config.ini` file. If you need to change the authentication configuration you can run `mrcli setup` to reset the configuration file.

## Required permissions for the Personal Access Token (PAT)
If you create a PAT before the **Mediumroast for GitHub** repository exists the required scope is for **all repositories** in your organization. At PAT renewal or if you want to reduce the scope to only the **Mediumroast for GitHub** repository this can be done later. The Personal Access Token must have the following permissions on all repositories to perform the necessary actions including setup.

- `Actions`: read/write
- `Administration`: read/write
- `Contents`: read/write
- `Metadata`: read
- `Pull requests`: read/write
- `Workflows`: read/write

For background and directions on creating a PAT see the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).


# Administrative CLIs
To enable setup and operational reporting of **Mediumroast for GitHub** several CLIs are available, each is described below.

## Storage reporting
Reports storage consumed by **Mediumroast for GitHub**. A screenshot showing the usage information and outputs for major functions is included below.
### Command(s) run
- `mrcli t`
- `mrcli storage`

### Screenshot with ouput
![Screenshot 2024-09-04 at 8 23 17 PM](https://github.com/user-attachments/assets/dba9738f-e093-4415-9ec7-1031f66cf6d1)

## Actions
Reports actions minutes consumed by **Mediumroast for GitHub** and enables a user to update their repository as new versions of actions are released. A screenshot showing the usage information and outputs for major functions is included below.
### Command(s) run
- `mrcli actions`
- `mrcli a --update`

### Screenshot with ouput
![Screenshot 2024-09-04 at 8 23 55 PM](https://github.com/user-attachments/assets/d9ea51fc-7609-4abb-9cbe-6e010baacb50)


## User reporting
Reports on all users who can access the repository that contains the **Mediumroast for GitHub**. A screenshot showing the usage information and outputs for major functions is included below, and notice, user names and other personally identifiable information has been redacted from the screenshot below.
### Command(s) run
Expand All @@ -12,15 +47,6 @@ Reports on all users who can access the repository that contains the **Mediumroa
### Screenshot with ouput
<img width="1178" alt="users_util" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/994787aa-ec26-4cb0-99a1-b670b9d929ff">

## Billing reporting
Provides reports for consumed actions and repository storage consumed by the organization that has installed and is using **Mediumroast for GitHub**. A screenshot showing the usage information and outputs for major functions is included below.
### Command(s) run
- `mrcli b`
- `mrcli b --storage`
- `mrcli b --actions`
### Screenshot with ouput
<img width="1178" alt="billings_util" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/4a715d07-b168-41ce-9054-33bf70af8086">

## Setup
To help users quickly get on board with **Mediumroast for GitHub** the setup CLI is used. This CLI creates the `${HOME}/.mediumroast/config.ini` file, creates the repository including key directories, and creates two initial companies. A screencast video showing the process for setting up the CLI environment and creating two companies is available below.

Expand All @@ -31,6 +57,18 @@ To help users quickly get on board with **Mediumroast for GitHub** the setup CLI

https://github.com/mediumroast/mediumroast_js/assets/10818650/68c08502-4f59-4981-a001-0d9c9bd1d4d2

# Deprecated commands
The following commands are deprecated, are disabled and will be removed in a future release of the CLI.

## Billing reporting
Is replaced by `storage` and `actions` commands in **Mediumroast for GitHub**. If you run this command it will immediately exit stating it is no longer supported.

### Command(s) run
- `mrcli b`
- `mrcli billing`



---

[[Company Subcommand](https://github.com/mediumroast/mediumroast_js/blob/main/cli/Company.md)] | [[Interaction Subcommand](https://github.com/mediumroast/mediumroast_js/blob/main/cli/Interaction.md)]
Expand Down
67 changes: 67 additions & 0 deletions cli/actions/actions/basic-reporting/companies.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
const mrMarkdownBuilder = require('mr_markdown_builder')

// Globals
const MAPS_WARNING = `**Notice:** If you are using Safari and had previously disabled \`Prevent cross-site tracking\` feature in the \`Privacy tab\` in Safari's preferences, you can now reenable it since this bug has been fixed by GitHub.${mrMarkdownBuilder.cr()}${mrMarkdownBuilder.cr()}`

function createCompaniesMap (companies) {
// Filter out companies with unknown latitude or longitude
companies = companies.filter((company) => company.latitude !== 'Unknown' && company.longitude !== 'Unknown')
// Create the map
let map = mrMarkdownBuilder.h1('Company Locations')
map += MAPS_WARNING
map += mrMarkdownBuilder.geojson({
type: 'FeatureCollection',
features: companies.map((company) => {
return {
type: 'Feature',
geometry: {
type: 'Point',
coordinates: [company.longitude, company.latitude]
},
properties: {
name: company.name,
description: company.description,
role: company.role,
url: company.url
}
}
})
})
// return the map
return mrMarkdownBuilder.cr() + map
}

function createCompaniesReport (companies) {
let readme = `[${mrMarkdownBuilder.link('Back to main README', '../README.md')}]\n`
readme += mrMarkdownBuilder.hr()
readme += mrMarkdownBuilder.h1('Introduction')
readme += `There are currently \`${companies.length}\` companies in the repository. The table below lists all available companies and some of their firmographics. Click on the company name to view the company's profile. Below the table is a map of all companies in the repository. Click on a company's marker to view additional company information in context.`
readme += mrMarkdownBuilder.h1('Table of Companies')
// Create the table header
const tableHeader = mrMarkdownBuilder.tableHeader(['Company Name', 'Company Type', 'Company Role', 'Company Region'])
// Create the table rows
const tableRows = companies.map((company) => {
const companyRow = [
mrMarkdownBuilder.link(company.name, `./${encodeURI(company.name.replace(/[\s,.\?!]/g, ''))}.md`),
company.company_type,
company.role,
company.region
]
return companyRow
})
// Create the table
const companyTable = tableHeader + "\n" + mrMarkdownBuilder.tableRows(tableRows)
// Create the README.md file
readme += companyTable
// Add a line break
readme += mrMarkdownBuilder.cr() + mrMarkdownBuilder.hr()
// Call the createMap function
readme += mrMarkdownBuilder.cr() + createCompaniesMap(companies)
// Return the file content
return readme

}

module.exports = {
createCompaniesReport
}
Loading

0 comments on commit 5acff49

Please sign in to comment.