docs: Introduce comprehensive agent guidance and Gitea API documentation
This commit adds new documentation to enhance agent readiness within the repository: - `AGENTS.md`: Provides a high-level overview of the project's purpose, technical stack, key workflows, and repository structure. - `.agents/gitea_api.md`: Contains detailed instructions and examples for programmatic interaction with the Gitea API, covering operations like fetching and creating issues/pull requests, along with a quick reference of API capabilities. These additions aim to streamline future autonomous operations by centralizing essential repository knowledge and API usage guidelines. It replaces previous ad-hoc methods for interacting with Gitea.
This commit was merged in pull request #17.
This commit is contained in:
61
.agents/gitea_api.md
Normal file
61
.agents/gitea_api.md
Normal file
@@ -0,0 +1,61 @@
|
||||
## Working with Gitea (API Guidance)
|
||||
|
||||
### Gitea API Features (Quick Reference)
|
||||
|
||||
The Gitea API provides extensive functionality for repository management, user interaction, and project oversight. Key features include:
|
||||
|
||||
* **Repository Management**: Create, delete, edit repositories; manage branches, commits, and tags.
|
||||
* **Issues & Pull Requests**: Create, view, update issues and pull requests; manage comments, labels, and milestones.
|
||||
* **User Management**: Access user profiles, manage SSH keys, GPG keys, and email addresses.
|
||||
* **Organization & Teams**: Interact with organizations and their associated teams.
|
||||
* **Notifications**: Manage user notifications.
|
||||
* **Activity Feeds**: Retrieve user and repository activity.
|
||||
* **Webhooks**: Configure webhooks for repository events.
|
||||
|
||||
For complete details and all available endpoints, refer to the [Gitea Swagger API Documentation](https://code.kiers.eu/swagger.v1.json).
|
||||
|
||||
This repository is hosted on Gitea. Direct API calls are often required for tasks like fetching issues, creating pull requests, etc., as specific tools might not always be available.
|
||||
|
||||
**Base URL:** `https://code.kiers.eu`
|
||||
**API Endpoint Prefix:** `/api/v1`
|
||||
**Repository Path:** `newsletter-to-web/newsletter-to-web`
|
||||
|
||||
You can use `curl` with the `FORGEJO_TOKEN` (which serves as your Gitea token) for authentication.
|
||||
|
||||
### Key API Interactions:
|
||||
|
||||
1. **Fetch Issues:**
|
||||
To get a list of all open issues for this repository:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer ${FORGEJO_TOKEN}" https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/issues
|
||||
```
|
||||
|
||||
2. **Fetch Pull Requests (Merge Requests):**
|
||||
Gitea uses "pull requests" in its API, though the UI might call them "merge requests."
|
||||
```bash
|
||||
curl -H "Authorization: Bearer ${FORGEJO_TOKEN}" https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/pulls
|
||||
```
|
||||
|
||||
3. **Create an Issue:**
|
||||
You would typically `POST` to the issues endpoint. The `labels` field expects an array of label IDs. Example (replace with actual data):
|
||||
```bash
|
||||
curl -X POST -H "Authorization: Bearer ${FORGEJO_TOKEN}" -H "Content-Type: application/json" -d '{
|
||||
"title": "New Issue Title",
|
||||
"body": "Description of the new issue.",
|
||||
"labels": [1, 2] # Use numerical label IDs
|
||||
}' https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/issues
|
||||
```
|
||||
*Note: You would need to fetch available labels and their IDs first if you want to apply them.*
|
||||
|
||||
4. **Create a Pull Request:**
|
||||
You would typically `POST` to the pulls endpoint. Example (replace with actual data and branches):
|
||||
```bash
|
||||
curl -X POST -H "Authorization: Bearer ${FORGEJO_TOKEN}" -H "Content-Type: application/json" -d '{
|
||||
"head": "your-branch-name",
|
||||
"base": "main",
|
||||
"title": "DRAFT: My New Pull Request",
|
||||
"body": "Detailed description of changes in this PR."
|
||||
}' https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/pulls
|
||||
```
|
||||
* `head`: The branch with your changes.
|
||||
* `base`: The branch you want to merge into (e.g., `main`).
|
||||
56
AGENTS.md
Normal file
56
AGENTS.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# AGENTS.md for newsletter-to-web
|
||||
|
||||
This document provides an overview and operational guidance for AI agents working with the `newsletter-to-web` repository, hosted on Gitea.
|
||||
|
||||
## Project Overview
|
||||
|
||||
The `newsletter-to-web` project is a Rust-based command-line application designed to convert email newsletters into a static Atom feed and individual HTML web pages. Its primary goal is to provide a privacy-preserving way to consume newsletters, allowing users to read them in a feed reader or a web browser without tracking elements.
|
||||
|
||||
## Technical Stack
|
||||
|
||||
* **Primary Language:** Rust (evident from `Cargo.toml`, `Cargo.lock`, and crate mentions in the changelog and issues).
|
||||
* **Build System:** Cargo (Rust's package manager and build tool).
|
||||
* **Email Handling:** IMAP protocol for fetching emails.
|
||||
* **Output:** Generates Atom feed (`.xml`) and static HTML files.
|
||||
|
||||
## Key Workflows
|
||||
|
||||
### 1. Initial Setup and Dependencies
|
||||
|
||||
The project uses Cargo. Dependencies are managed via `Cargo.toml` and `Cargo.lock`. A simple `cargo build` should compile the project.
|
||||
|
||||
### 2. Fetching Emails
|
||||
|
||||
Emails are fetched from an IMAP server and stored locally.
|
||||
`newsletter-to-web fetch-from-imap -s <imap.example.com> -u <email@example.com> -p <password>`
|
||||
|
||||
### 3. Building the Feed and HTML Files
|
||||
|
||||
After fetching, the stored emails are processed to generate the Atom feed and HTML pages.
|
||||
`newsletter-to-web --include-html build-feed newsletters.example.org`
|
||||
This command outputs files into the `output/` directory.
|
||||
|
||||
### 4. Running Tests
|
||||
|
||||
(Assumption: Standard Rust test practices apply)
|
||||
To run unit and integration tests:
|
||||
`cargo test`
|
||||
|
||||
## Repository Structure
|
||||
|
||||
* `Cargo.toml`: Project manifest and dependency definitions.
|
||||
* `Cargo.lock`: Exact dependency versions for reproducible builds.
|
||||
* `src/`: Contains the Rust source code.
|
||||
* `main.rs`: Main entry point of the application.
|
||||
* `cli.rs`: Defines command-line interface arguments and subcommands.
|
||||
* `command/`: Contains implementations for various subcommands (e.g., `update.rs`).
|
||||
* `feed.rs`: Logic for generating the Atom feed.
|
||||
* `message.rs`: Defines structures for email messages.
|
||||
* `message_reader/`: Contains logic for reading messages (e.g., `imap.rs` for IMAP fetching).
|
||||
* `resources/`: Contains static resources like `feed.xsl` (for styling the feed) and `index.html` (for the output directory).
|
||||
* `systemd/`: Contains systemd service and timer files for automated operation.
|
||||
* `CHANGELOG.md`: Documents all notable changes.
|
||||
* `README.md`: General project information and usage instructions.
|
||||
|
||||
|
||||
For details on interacting with the Gitea API (issues, pull requests, etc.), refer to [.agents/gitea_api.md](.agents/gitea_api.md).
|
||||
Reference in New Issue
Block a user