Skip to content
This repository was archived by the owner on Dec 19, 2025. It is now read-only.

Commit 7fb170e

Browse files
axelrindleaxelrindle
committed
Prepare docs for v3 release
1 parent 44b7c20 commit 7fb170e

28 files changed

+626
-28
lines changed

‎docs/changelog/3/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Version 3️⃣",
3+
"position": 1,
4+
"link": {
5+
"type": "generated-index",
6+
"title": "v3 Changelogs"
7+
}
8+
}

‎docs/changelog/3/index.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# 3.0.0
2+
3+
> Released on `2013-01-14`
4+
5+
## Added
6+
7+
- A brand new CLI interface for usage in non Node.js projects.
8+
- A new option `forceRest`
9+
10+
## Changed
11+
12+
- `undefined` is returned instead of `null` in case of no found updates.
13+
- The usage of the GraphQL API may be explicitly disabled by passing `false` for the `token`.
14+
- The GraphQL queries have been optimized in terms of stability and reliability.
15+
- Using [Octokit](https://github.com/octokit) under the hood.
16+
17+
## Removed
18+
19+
- The `reduceTraffic` option.
20+
- Official support for Node.js below version 12. Older version might work but are not tested.
21+
22+
## Security
23+
24+
- Dependencies have been updated.
25+
- The project is officially built and released with Node.js 18.
26+
27+
## Other
28+
29+
- Documentation an other stuff is now hosted at https://axelrindle.github.io/github-version-checker/
30+
- Moved to TypeScript.
31+
- Using [Lerna](https://lerna.js.org/) for monorepo management.

‎docs/changelog/unreleased.md‎

Lines changed: 1 addition & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,5 @@
11
---
2-
sidebar_position: 1
2+
sidebar_position: 0
33
---
44

55
# 🔜 Unreleased
6-
## Added
7-
8-
- A brand new CLI interface for usage in non Node.js projects.
9-
10-
## Changed
11-
12-
- `undefined` is returned instead of `null` in case of no found updates.
13-
- The usage of the GraphQL API may be explicitly disabled by passing `false` for the `token`.
14-
- The GraphQL queries have been optimized in terms of stability and reliability.
15-
- Using [Octokit](https://github.com/octokit) under the hood.
16-
17-
## Removed
18-
19-
- The `reduceTraffic` option.
20-
- Official support for Node.js below version 12. Older version might work but are not tested.
21-
22-
## Security
23-
24-
- Dependencies have been updated.
25-
- The project is officially built and released with Node.js 18.
26-
27-
## Other
28-
29-
- Documentation an other stuff is now hosted at https://axelrindle.github.io/version-checker/
30-
- Moved to TypeScript.
31-
- Using [Lerna](https://lerna.js.org/) for monorepo management.

‎docs/versioned_docs/version-3.0.0/api.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
sidebar_position: 3
3+
sidebar_label: 🧩 API
4+
---
5+
6+
# API
7+
8+
```js
9+
// Require the module
10+
const versionCheck = require('@version-checker/core');
11+
12+
// Or import
13+
import versionCheck from '@version-checker/core'
14+
```
15+
16+
## `function versionCheck(options, [callback])`
17+
Performs an update check with the given options. The `callback` is optional, can be omitted to return a `Promise`.
18+
19+
### The `options` object
20+
Option | Description | Default Value | Introduction
21+
--- | --- | --- | ---
22+
token | A [personal access token](https://blog.github.com/2013-05-16-personal-api-tokens/) used to access the **Github GraphQL API (v4)**. Can be omitted and instead be read from an env variable called `GITHUB_API_TOKEN`. When no token can be found, the module will fall back to the **Github Rest API (v3)**. | `undefined` | `v2.0.0`
23+
repo | The name of your Github repository.| **None. Required.** | `v1.0.0`
24+
owner | The owner of your Github repository (usually your username).| **None. Required.** | `v1.0.0`
25+
currentVersion | Your app's current version. | **None. Required.** | `v1.0.0`
26+
fetchTags | Whether to fetch the repositories' git tags instead of the GitHub releases. Useful when no releases are created, but only tags. | `false` | `v1.0.0`
27+
latestOnly | Setting this to `true` will fetch the latest release only | `false` | `v2.2.0`
28+
excludePrereleases | Excludes pre-releases from checks. Currently only works when no token is specified. | `false` | `v2.3.0`
29+
forceRest | Will use the Github REST API (v3) even with a supplied token. | `false` | `v3.0.0`
30+
31+
### The `callback` function (optional)
32+
Should be of the following form:
33+
```javascript
34+
function(error, update) {
35+
// ...your code
36+
}
37+
```
38+
* `error`:
39+
* If an error occurs, this holds the error message. `null` if no error occurs.
40+
* `update`:
41+
* An object in the format specified below. `null` if no update was found.
42+
43+
### Return type
44+
45+
The function returns a `CheckResult` which has the following structure:
46+
47+
```typescript
48+
interface CheckResult {
49+
src: string
50+
type: string
51+
update: ReleaseDescriptor | TagDescriptor | undefined
52+
}
53+
```
54+
55+
#### Properties
56+
##### `src`
57+
58+
States which API endpoint has been used.
59+
60+
Possible values:
61+
62+
- `rest`
63+
- `graphql`
64+
65+
##### `type`
66+
67+
States whether releases or tags have been fetched.
68+
69+
Possible values:
70+
71+
- `releases`
72+
- `tags`
73+
74+
##### `update`
75+
76+
Holds the actual data on a possible update. For structure details refer to [Object schemes](#object-schemes).
77+
78+
It is `undefined` in case no update could be found.
79+
80+
### Using `Promise`
81+
You can omit the `callback` function to return a `Promise`, which resolves with the `update` object.
82+
83+
## Object schemes
84+
### ReleaseDescriptor
85+
When fetching releases, an object with the following structure will be returned:
86+
```typescript
87+
interface ReleaseDescriptor {
88+
name: string
89+
tag: TagDescriptor
90+
isPrerelease: boolean
91+
isDraft: boolean
92+
publishedAt: string
93+
url: string
94+
}
95+
```
96+
97+
### TagDescriptor
98+
When fetching tags, you will receive an object with the following structure:
99+
```typescript
100+
interface TagDescriptor {
101+
name: string
102+
}
103+
```

‎docs/versioned_docs/version-3.0.0/cli/01-installation.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Installation
2+
3+
## npm
4+
5+
```shell
6+
npm install -g @version-checker/cli
7+
```
8+
9+
## Binary
10+
11+
Download a binary version from the [releases page](https://github.com/axelrindle/github-version-checker/releases).

‎docs/versioned_docs/version-3.0.0/cli/02-examples.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Usage Examples
2+
3+
## Basic
4+
5+
```shell
6+
$ version-checker \
7+
--owner axelrindle \
8+
--repository version-checker \
9+
--current-version 2.2.0
10+
```
11+
12+
```
13+
An update is available! v3.0.0
14+
You are on version 2.3.0!
15+
```
16+
17+
## With json output
18+
19+
```shell
20+
$ version-checker --json \
21+
--owner axelrindle \
22+
--repository version-checker \
23+
--current-version 2.2.0
24+
```
25+
26+
```json
27+
{
28+
"type": "outdated",
29+
"data": {
30+
"name": "v2.3.0",
31+
"tag": {
32+
"name": "2.3.0"
33+
},
34+
"isPrerelease": false,
35+
"isDraft": false,
36+
"publishedAt": "2022-03-18T15:22:03Z",
37+
"url": "https://github.com/axelrindle/github-version-checker/releases/tag/2.3.0"
38+
}
39+
}
40+
```

‎docs/versioned_docs/version-3.0.0/cli/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "⌨️ Command Line Interface (CLI)",
3+
"position": 5,
4+
"link": {
5+
"type": "doc",
6+
"id": "cli/index"
7+
}
8+
}

‎docs/versioned_docs/version-3.0.0/cli/index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Command Line Interface (CLI)
2+
3+
The CLI offers to perform a version check in non-Node.js environments.
4+
It supports plain-text and JSON-formatted output.
5+
6+
## Usage
7+
8+
```
9+
10+
$ version-checker [options]
11+
12+
Options
13+
-o, --owner The repository owner. May be a username or organization name.
14+
-r, --repository The repository name.
15+
-c, --current-version The current application version.
16+
-t, --tags Fetches tags instead of releases.
17+
--no-pre-releases Excludes pre-releases. (default false)
18+
--token A PAT to use.
19+
--json Outputs the raw result data as JSON. (default false)
20+
--verbose Enables verbose logging. (default false)
21+
-v, --version Displays current version
22+
-h, --help Displays this message
23+
24+
```

‎docs/versioned_docs/version-3.0.0/development.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
sidebar_position: 99
3+
sidebar_label: 👨‍💻 Development & Contributing
4+
---
5+
6+
# Development & Contributing
7+
8+
Be sure to read the [Code of Conduct](https://github.com/axelrindle/github-version-checker/blob/main/CODE_OF_CONDUCT.md)
9+
10+
## Setup
11+
12+
First of all clone the git repository :)
13+
14+
```shell
15+
$ git clone https://github.com/axelrindle/github-version-checker.git
16+
```
17+
18+
and then install the dependencies
19+
20+
```shell
21+
$ npm ci
22+
```
23+
24+
By running [`npm ci`](https://docs.npmjs.com/cli/v9/commands/npm-ci) instead of [`npm i`](https://docs.npmjs.com/cli/v9/commands/npm-install) it is ensured that the dependency tree is installed exactly as stated in the [`package-lock.json`](https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json) file. That guarantees the usage of identical dependency trees throughout development.
25+
26+
## Working on the packages
27+
28+
1. Bootstrap the Lerna environment
29+
30+
```shell
31+
$ npx lerna bootstrap
32+
```
33+
34+
2. Do your changes on a seperate branch, e.g. `feature/my-bug-fix`
35+
36+
## Contributing to the documentation
37+
38+
All documentation resided within the `docs/` directory. Is is built upon [Docusaurus](https://docusaurus.io/) and primarily written in Markdown.
39+
40+
Install dependencies using
41+
42+
```shell
43+
$ npm ci
44+
```
45+
46+
and start the development server by running
47+
48+
```shell
49+
$ npm start
50+
```
51+
52+
To produce a production build, run
53+
54+
```shell
55+
$ npm run build
56+
```
57+
58+
That produces a static site which can be served using
59+
60+
```shell
61+
$ npm run serve
62+
```

‎docs/versioned_docs/version-3.0.0/examples/01-basic/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "🥸 Basic",
3+
"position": 1,
4+
"link": {
5+
"type": "generated-index",
6+
"title": "Basic Examples"
7+
}
8+
}

0 commit comments

Comments
 (0)