initiate monorepo, add original github-trends
This commit is contained in:
martin-mfg
@@ -0,0 +1,96 @@
|
||||
# GitHub Trends API
|
||||
|
||||
GitHub Trends provides two methods to access GitHub Trends data: the Website Workflow at githubtrends.io and the API Workflow described below.
|
||||
|
||||
## Available Cards
|
||||
|
||||
After authenticating with either the public or private workflow (see below), users can create the following cards to display their GitHub Trends data:
|
||||
|
||||
- **[Languages Card](https://github.com/avgupta456/github-trends/blob/main/docs/API.md#languages-card)**: See your top languages over a given time interval, based on all commits to personal and open-source repositories.
|
||||
|
||||
- **[Repositories Card](https://github.com/avgupta456/github-trends/blob/main/docs/API.md#repositories-card)**: See your top repositories based on lines of code contributed over a given time period. This includes both personal and open-source repositories.
|
||||
|
||||
# Authentication
|
||||
|
||||
You will need to create an account with GitHub Trends to create cards. The account is used to assosciate queries to the GitHub API made on your behalf with your GitHub account's API quota. We use less than 5% of your quota in almost all scenarios. There are two levels of authentication possible:
|
||||
|
||||
- Public Workflow: The Public Workflow asks for read-only permission to public information. This will allow us to analyze your public contributions and repositories only.
|
||||
- Private Workflow: The Private Workflow asks for read and write permission to public and private information. This will allow us to analyze your entire contribution history. See [the FAQ](https://github.com/avgupta456/github-trends/blob/main/docs/FAQ.md) for further information.
|
||||
|
||||
You will only need to authenticate once with GitHub Trends. Subsequent requests will use your stored access token.
|
||||
|
||||
For the public workflow, visit
|
||||
|
||||
```md
|
||||
https://api.githubtrends.io/auth/signup/public
|
||||
```
|
||||
|
||||
For the private workflow, visit
|
||||
|
||||
```md
|
||||
https://api.githubtrends.io/auth/signup/private
|
||||
```
|
||||
|
||||
You will be prompted to allow access, and (hopefully) redirected to a success screen.
|
||||
|
||||
If you have previously authenticated with the public workflow, you can upgrade to the private workflow by using the private link. If you would like to delete your account, go to your GitHub settings and revoke the access token.
|
||||
|
||||
# Languages Card
|
||||
|
||||
See your top languages over a given time interval, based on all commits to personal and open-source repositories. Your top five languages will be displayed. Due to the approximations used internally, LOC metrics will be rounded to the nearest 100 lines.
|
||||
|
||||
After authentication, visit
|
||||
|
||||
```md
|
||||
https://api.githubtrends.io/user/svg/{user_id}/langs
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
The following customization options are available:
|
||||
|
||||
| Option | Description | Default |
|
||||
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
|
||||
| `time_range` | Specifies the time range to query statistics for. Valid options are `one_month`, `three_months`, `six_months`, `one_year`, and `all_time`. | `one_month` |
|
||||
| `include_private` | Determines if private contributions are included (requires private workflow). | `false` |
|
||||
| `compact` | Determines if compact layout is used (forces percentages over LOC) | `false` |
|
||||
| `use_percent` | Valid if `compact=false`, determines if line of code (default) or percentages are displayed. | `false` |
|
||||
| `loc_metric` | Options are LOC added (`added`) and LOC changed (`changed`). | `added` |
|
||||
| `theme` | Theme to use for the card. See [docs/THEME.md](https://github.com/avgupta456/github-trends/blob/main/docs/THEME.md) for options. | `classic` |
|
||||
|
||||
Customizations can be appended to the endpoint, separated first with `?` and subsequently with `&`.
|
||||
|
||||
## Example
|
||||
|
||||
Endpoint: `https://api.githubtrends.io/user/svg/avgupta456/langs?time_range=three_months&include_private=true&compact=true`
|
||||
|
||||
[](https://githubtrends.io)
|
||||
|
||||
# Repositories Card
|
||||
|
||||
After authentication, visit
|
||||
|
||||
```md
|
||||
https://api.githubtrends.io/user/svg/{user_id}/repos
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
The following customization options are available:
|
||||
|
||||
| Option | Description | Default |
|
||||
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
|
||||
| `time_range` | Specifies the time range to query statistics for. Valid options are `one_month`, `three_months`, `six_months`, `one_year`, and `all_time`. | `one_month` |
|
||||
| `include_private` | Determines if private contributions are included (requires private workflow). | `false` |
|
||||
| `group` | Options are `none` (default), `other` (group all other repos together), and `private` (force private repos to be grouped) | `none` |
|
||||
| `use_percent` | Valid if `compact=false`, determines if line of code (default) or percentages are displayed. | `false` |
|
||||
| `loc_metric` | Options are LOC added (`added`) and LOC changed (`changed`). | `added` |
|
||||
| `theme` | Theme to use for the card. See [docs/THEME.md](https://github.com/avgupta456/github-trends/blob/main/docs/THEME.md) for options. | `classic` |
|
||||
|
||||
Customizations can be appended to the endpoint, separated first with `?` and subsequently with `&`.
|
||||
|
||||
## Example
|
||||
|
||||
Endpoint: `https://api.githubtrends.io/user/svg/avgupta456/repos?time_range=one_year&include_private=true&group=private&loc_metric=changed&theme=dark`
|
||||
|
||||
[](https://githubtrends.io)
|
||||
@@ -0,0 +1,15 @@
|
||||
# GitHub Trends
|
||||
|
||||
If you are interested in contributing to GitHub Trends, take a look through the codebase and at the open issues. Follow the guide below to set up your local environment, and contact Abhijit Gupta at `avgupta456@gmail.com` if you have any questions or need additional permissions. Thank you in advance for contributing!
|
||||
|
||||
## Local Development
|
||||
|
||||
First, copy `backend/.env-template` into `backend/.env` and fill in the missing variables. Similarly, copy `frontend/.env-template` into `frontend/.env` and fill in the missing variables. Create a Google Cloud Platform service account and include the key in `backend/gcloud_key.json`. Then run:
|
||||
|
||||
With Python3.11, install the dependencies from `backend/requirements.txt` and run `yarn start`.
|
||||
|
||||
With Node16 and Yarn, install the dependencies from `frontend/package.json` and run on a separate terminal window `yarn start-trends`.
|
||||
|
||||
## Testing
|
||||
|
||||
Create a pull request and let GitHub Actions run. Alternatively, explore `.github/backend.yaml` and `.github/frontend.yaml` to run tests locally. Backend coverage must increase for PRs to be merged.
|
||||
@@ -0,0 +1,38 @@
|
||||
# FAQ
|
||||
|
||||
The FAQ is in progress. Reach out if you have any unanswered questions or concerns.
|
||||
|
||||
---
|
||||
|
||||
**Question**: Does GitHub Trends have access to my private code contributions?
|
||||
|
||||
**Answer**: GitHub Trends requires an OAuth access token to make requests on your behalf. The standard public workflow creates a token with read-only access to strictly public information. **This access token can not view or edit any private contributions**.
|
||||
|
||||
Alternatively, users can use the private workflow which creates a token with read and write access to private information. Although GitHub Trends only uses it's read access, GitHub does not allow read-only private access (see [an open issue from 2015](https://github.com/jollygoodcode/jollygoodcode.github.io/issues/6)). While one may scan the repository to confirm this statement, there are inherent security risks to this overallocation. If this poses an issue to you, please use the public workflow instead.
|
||||
|
||||
**Question**: How can I display my images side by side?
|
||||
|
||||
**Answer**: Use HTML (credit: [github-readme-stats](https://github.com/anuraghazra/github-readme-stats#quick-tip-align-the-repo-cards))
|
||||
|
||||
```
|
||||
<a href="https://githubtrends.io">
|
||||
<img align="center" src="https://api.githubtrends.io/user/svg/avgupta456/langs" />
|
||||
</a>
|
||||
<a href="https://githubtrends.io">
|
||||
<img align="center" src="https://api.githubtrends.io/user/svg/avgupta456/repos" />
|
||||
</a>
|
||||
```
|
||||
|
||||
**Question**: How can I see my stats without giving GitHub Trends my access token?
|
||||
|
||||
**Answer**: You will need to run the code locally. Clone the repository, navigate to the `backend` folder, install the dependencies (`pip install -r requirements.txt`), and then run the following script:
|
||||
|
||||
```bash
|
||||
python ./scripts/local.py --user_id=USER_ID --access_token=ACCESS_TOKEN --start_date=2023-01-01 --end_date=2023-01-31 --output_dir=OUTPUT_DIR
|
||||
```
|
||||
|
||||
The script will output the raw and processed JSONs into the output directory specified.
|
||||
|
||||
**Question**: What if I find a bug, or want to contribute?
|
||||
|
||||
**Answer**: Raise an [issue](https://github.com/avgupta456/github-trends/issues/new) or [pull request](https://github.com/avgupta456/github-trends/compare) through GitHub. I would be happy to discuss and implement any suggestions or improvements.
|
||||
@@ -0,0 +1,6 @@
|
||||
The following themes are available for all GitHub Trends cards:
|
||||
|
||||
| Themes | | |
|
||||
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [](https://githubtrends.io) | [](https://githubtrends.io) | [](https://githubtrends.io) |
|
||||
| [](https://githubtrends.io) | [](https://githubtrends.io) | [](https://githubtrends.io) |
|
||||
Reference in New Issue
Block a user