From ac1f3984229567bf28abcf8c1140246106541cf0 Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Sat, 14 Dec 2024 01:32:22 +0100 Subject: [PATCH] fix(docs): Updated project metadata and expanded documentation for installation and usage. --- changelog.md | 6 ++ npmextra.json | 17 +++++- package.json | 17 +++++- readme.md | 129 ++++++++++++++++++++++++++++++++++++++- ts/00_commitinfo_data.ts | 4 +- 5 files changed, 164 insertions(+), 9 deletions(-) diff --git a/changelog.md b/changelog.md index f2330ee..383f0d5 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,11 @@ # Changelog +## 2024-12-14 - 1.6.1 - fix(docs) +Updated project metadata and expanded documentation for installation and usage. + +- Updated description and keywords in package.json and npmextra.json. +- Significant expansion of the README.md with detailed installation, usage, and feature instructions. + ## 2024-12-14 - 1.6.0 - feat(core) Add changelog fetching and parsing functionality diff --git a/npmextra.json b/npmextra.json index 4f720a2..6e71537 100644 --- a/npmextra.json +++ b/npmextra.json @@ -5,10 +5,23 @@ "githost": "code.foss.global", "gitscope": "foss.global", "gitrepo": "codefeed", - "description": "a module for creating feeds for code development", + "description": "The @foss.global/codefeed module is designed for generating feeds from Gitea repositories, enhancing development workflows by processing commit data and repository activities.", "npmPackagename": "@foss.global/codefeed", "license": "MIT", - "projectDomain": "foss.global" + "projectDomain": "foss.global", + "keywords": [ + "codefeed", + "Gitea", + "commits", + "changelog", + "repository", + "development tools", + "npm", + "module", + "code analysis", + "activity feed", + "version control" + ] } }, "npmci": { diff --git a/package.json b/package.json index 0222c1a..cace193 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@foss.global/codefeed", "version": "1.6.0", "private": false, - "description": "a module for creating feeds for code development", + "description": "The @foss.global/codefeed module is designed for generating feeds from Gitea repositories, enhancing development workflows by processing commit data and repository activities.", "exports": { ".": "./dist_ts/index.js", "./interfaces": "./dist_ts/interfaces/index.js" @@ -48,5 +48,18 @@ "cli.js", "npmextra.json", "readme.md" + ], + "keywords": [ + "codefeed", + "Gitea", + "commits", + "changelog", + "repository", + "development tools", + "npm", + "module", + "code analysis", + "activity feed", + "version control" ] -} +} \ No newline at end of file diff --git a/readme.md b/readme.md index acc5db7..bbce467 100644 --- a/readme.md +++ b/readme.md @@ -1,7 +1,130 @@ +```markdown # @foss.global/codefeed -a module for creating feeds for code development +A module for creating feeds for code development. -## How to create the docs +## Install -To create docs run gitzone aidoc. +To install the `@foss.global/codefeed` package, you can run the following npm command in your project directory: + +```bash +npm install @foss.global/codefeed +``` + +Ensure that you have a compatible version of Node.js installed and that your project is set up to support ECMAScript modules. The `@foss.global/codefeed` module uses ESM syntax. + +## Usage + +The `@foss.global/codefeed` package is designed to help developers generate feeds for code developments, specifically targeting Gitea repositories. It fetches and processes commit data, changelogs, and repository activities for further analysis or visualization. Here, we'll delve into how you can utilize the different features of the `CodeFeed` class. + +### Setting Up CodeFeed + +To get started, import the `CodeFeed` class from the module: + +```typescript +import { CodeFeed } from '@foss.global/codefeed'; +``` + +Then, create an instance of `CodeFeed`. You'll need the base URL of your Gitea instance and optionally an API token if your repositories require authentication: + +```typescript +const codeFeed = new CodeFeed('https://your-gitea-instance-url.com', 'your-api-token'); +``` + +The constructor can also accept a `lastRunTimestamp` which indicates the last time a sync was performed. If not provided, it defaults to 24 hours prior to the current time. + +### Fetching Commits + +One of the core functionalities of CodeFeed is fetching commits from a Gitea instance. By calling `fetchAllCommitsFromInstance`, you can retrieve commits across multiple repositories: + +```typescript +(async () => { + try { + const commits = await codeFeed.fetchAllCommitsFromInstance(); + console.log(commits); + } catch (error) { + console.error('An error occurred while fetching commits:', error); + } +})(); +``` + +This method scans all organizations and repositories, filters commits tagged within the last 24 hours, and enriches them with metadata like changelogs or npm publication status. + +Each commit object in the resulting array conforms to the `ICommitResult` interface, containing details such as: +- `baseUrl` +- `org` +- `repo` +- `timestamp` +- `hash` +- `commitMessage` +- `tagged` (boolean) +- `publishedOnNpm` (boolean) +- `prettyAgoTime` (human-readable relative time) +- `changelog` (text from the `changelog.md` associated with a commit) + +### Understanding the Data Fetch Process + +#### Fetching Organizations + +The `fetchAllOrganizations` method collects all organizations within the Gitea instance: + +```typescript +const organizations = await codeFeed.fetchAllOrganizations(); +console.log('Organizations:', organizations); +``` + +This method interacts with the Gitea API to pull organization names, aiding further requests that require organization context. + +#### Fetching Repositories + +Repositories under these organizations can be retrieved using `fetchAllRepositories`: + +```typescript +const repositories = await codeFeed.fetchAllRepositories(); +console.log('Repositories:', repositories); +``` + +Here, filtering by organization can help narrow down the scope further when dealing with large instances. + +#### Fetching Tags and Commits + +To handle repository-specific details, use: + +- `fetchTags(owner: string, repo: string)`: Appropriately handles paginated tag data within a repository. + +- `fetchRecentCommitsForRepo(owner: string, repo: string)`: Gathers commit data specific to the past 24 hours for a given repository. + +```typescript +const tags = await codeFeed.fetchTags('orgName', 'repoName'); +const recentCommits = await codeFeed.fetchRecentCommitsForRepo('orgName', 'repoName'); + +console.log('Tags:', tags); +console.log('Recent Commits:', recentCommits); +``` + +### Changelog Integration + +Loading changelog content from a repository is integrated into the flow with `loadChangelogFromRepo`. This can be accessed when processing specific commits: + +```typescript +await codeFeed.loadChangelogFromRepo('org', 'repo'); +const changelog = codeFeed.getChangelogForVersion('1.0.0'); +console.log('Changelog for version 1.0.0:', changelog); +``` + +### Reacting to Repository Activity + +The method `hasNewActivity` checks for recent changes within an organization or a repository. This is particularly useful for setting up alerting systems or continuous integration triggers: + +```typescript +const hasActivity = await codeFeed.hasNewActivity({ orgName: 'orgName', repoName: 'repoName' }); +console.log('New activity detected:', hasActivity); +``` + +### Conclusion + +The `@foss.global/codefeed` module provides robust capabilities for extracting and managing feed data related to code developments in Gitea environments. Through systematic setup and leveraging API-driven methods, it becomes a valuable tool for developers aiming to keep track of software progress and changes efficiently. The integration hooks like changelog and npm verification further enrich its utility, offering consolidated insights into each commit's journey from codebase to published package. + +Explore integrating these capabilities into your development workflows to enhance tracking, deployment pipelines, or analytics systems within your projects. Remember to always handle API tokens securely and adhere to best practices when managing access to repository resources. Stay updated on any changes or enhancements to this module for further feature exposures or bug fixes. Happy coding! +``` +undefined \ No newline at end of file diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index aff4138..f23de12 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@foss.global/codefeed', - version: '1.6.0', - description: 'a module for creating feeds for code development' + version: '1.6.1', + description: 'The @foss.global/codefeed module is designed for generating feeds from Gitea repositories, enhancing development workflows by processing commit data and repository activities.' }