diff options
Diffstat (limited to 'docs/en/developers')
| -rw-r--r-- | docs/en/developers/01_Index.md | 29 | ||||
| -rw-r--r-- | docs/en/developers/02_First_steps.md (renamed from docs/en/developers/01_First_steps.md) | 0 | ||||
| -rw-r--r-- | docs/en/developers/02_Github.md | 67 | ||||
| -rw-r--r-- | docs/en/developers/03_Backend/01_Database_schema.md | 1 | ||||
| -rw-r--r-- | docs/en/developers/03_Backend/03_External_libraries.md | 1 | ||||
| -rw-r--r-- | docs/en/developers/06_Fever_API.md | 110 | ||||
| -rw-r--r-- | docs/en/developers/06_Reporting_Bugs.md | 66 |
7 files changed, 207 insertions, 67 deletions
diff --git a/docs/en/developers/01_Index.md b/docs/en/developers/01_Index.md new file mode 100644 index 000000000..fcd9204af --- /dev/null +++ b/docs/en/developers/01_Index.md @@ -0,0 +1,29 @@ +# FreshRSS Development + +## First Steps + +Start by creating your development environment. A guide to setting up FreshRSS's development environment can be found on [the appropriate page](02_First_steps.md). + +## After That + +* [Github Branching and Pushing](02_Github.md) +* [Running tests](03_Running_tests.md) +* [Creating a pull request](04_Pull_requests.md) +* [Releasing a new version](05_Release_new_version.md) +* [Reporting bugs](06_Reporting_Bugs.md) +* [Fever API](06_Fever_API.md) + +## Backend Development + +* [Making extensions for FreshRSS](03_Backend/05_Extensions.md) +* [Database Schema](03_Backend/01_Database_schema.md) +* [External libraries](03_Backend/03_External_libraries.md) +* [Changing source code](03_Backend/04_Changing_source_code.md) + +## Frontend Development + +* [View files](04_Frontend/01_View_files.md) +* [Design](04_Frontend/02_Design.md) + +## Minz +Minz is the homemade PHP framework used by FreshRSS. More information can be found [here](Minz/index.md).
\ No newline at end of file diff --git a/docs/en/developers/01_First_steps.md b/docs/en/developers/02_First_steps.md index 7b3a4c11f..7b3a4c11f 100644 --- a/docs/en/developers/01_First_steps.md +++ b/docs/en/developers/02_First_steps.md diff --git a/docs/en/developers/02_Github.md b/docs/en/developers/02_Github.md index a898dc23e..953785d4f 100644 --- a/docs/en/developers/02_Github.md +++ b/docs/en/developers/02_Github.md @@ -1,70 +1,3 @@ -# Reporting a bug or a suggestion - -Despite the care given to FreshRSS, it's still possible that bugs occur. The project is young and development is dynamic, so it can be corrected quickly. You might also have a feature in mind that doesn't yet exist. Regardless whether your idea seems silly, far-fetched, useless or too specific, please don't hesitate to propose it to us! "Ideas in the air" often find an attentive ear. It's new external perspectives that make the project evolve the most. - -If you're convinced that you should be heard, here's how you can go about it. - -## On GitHub - -GitHub is the ideal platform to submit your requests. It allows us to discuss a problem or suggestion with others and it often generates new ideas. Let's not neglect this "social" aspect! - - 1. [Go to the bug ticket manager](https://github.com/FreshRSS/FreshRSS/issues) - 2. Start by checking if a similar request hasn't already been made. If so, please feel free to add your voice to the request. - 3. If your request is new, [open a new bug ticket](https://github.com/FreshRSS/FreshRSS/issues/new) - 4. Finally, write your request. If you're fluent in English, it's the preferred language because it allows for discussion with the largest number of people. - 5. Please follow the tips below to make it easier to let your ticket be heard. - -## Informal - -Not everyone likes or uses GitHub for a variety of legitimate reasons. That is why you can also contact us in a more informal way. - -* On [our Mattermost chat](https://framateam.org/signup_user_complete/?id=e2680d3e3128b9fac8fdb3003b0024ee) -* On [the mailing lists](https://freshrss.org/announce-of-the-mailing-lists.html) -* At events / meetings around Free Software -* Over a beer in a bar -* Etc. - -## Tips - -Here are some tips to help you present your bug report or suggestion: - - -* **Pay attention to spelling**. Even if it's not always easy, try your best! -* **Give an explicit title to your request**, even if it's a bit long. This not only helps us understand your request, but also to find your ticket later. -* **One request = one ticket.** You may have lots of ideas while being afraid to spam the bug manager: it doesn't matter. It's better to have a few too many tickets than too many requests in one. We'll close and consolidate requests when possible. -* If you report a bug, think about **providing us with the FreshRSS logs** (accessible in the FreshRSS `data/log/` folder) and the **PHP logs** (the location may vary by distribution, but consider searching in `/var/log/httpd` or `/var/log/apache`). -* If you can't find the log files, specify it in your ticket so we know you've already searched. -* Not all bugs require logs, but if you have any doubts, it is better to provide them to us. Logs are important and very useful for debugging! -* The logs may reveal confidential information, so **be careful not to disclose anything sensitive.** - -In addition, when facing a bug, you're encouraged to follow this message format (from the [Sam & Max website](http://sametmax.com/template-de-demande-daide-en-informatique/): - -### What's my goal? - -Give the general context of what you were trying to do. - -### What have I been trying to do? - -Explain step by step what you have done so that we can reproduce the bug. - -### What results have I achieved? - -The bug: what you see that shouldn't have happened. Here you can provide the logs. - -### What was the expected result? - -So that we understand what you consider to be the problem. - -### What are my circumstances? - -Remember to give the following information if you know it: - - 1. Which browser? Which version? - 2. Which server: Apache, Nginx? Which version? - 3. Which version of PHP? - 4. Which database: SQLite, MySQL, MariaDB, PostgreSQL? Which version? - 5. Which distribution runs on the server? And... which version? - # Branching ## Basic diff --git a/docs/en/developers/03_Backend/01_Database_schema.md b/docs/en/developers/03_Backend/01_Database_schema.md index e69de29bb..1978eabea 100644 --- a/docs/en/developers/03_Backend/01_Database_schema.md +++ b/docs/en/developers/03_Backend/01_Database_schema.md @@ -0,0 +1 @@ +# Database Schema
\ No newline at end of file diff --git a/docs/en/developers/03_Backend/03_External_libraries.md b/docs/en/developers/03_Backend/03_External_libraries.md index e69de29bb..2f6ca8efb 100644 --- a/docs/en/developers/03_Backend/03_External_libraries.md +++ b/docs/en/developers/03_Backend/03_External_libraries.md @@ -0,0 +1 @@ +# External Libraries diff --git a/docs/en/developers/06_Fever_API.md b/docs/en/developers/06_Fever_API.md new file mode 100644 index 000000000..0a0da90a5 --- /dev/null +++ b/docs/en/developers/06_Fever_API.md @@ -0,0 +1,110 @@ +# FreshRSS - Fever API implementation + +See the [page about our Google Reader compatible API](06_Mobile_access.md) for another possibility +and general aspects of API access. + +## RSS clients + +There are many RSS clients that support the Fever API, but they seem to understand the Fever API a bit differently. +If your favourite client doesn't work properly with this API, please create an issue and we'll have a look. +But we can **only** do that for free clients. + +### Usage & Authentication + +Before you can start using this API, you have to enable and setup API access, which is [documented here](https://freshrss.github.io/FreshRSS/en/users/06_Mobile_access.html), +and then reset the user’s API password. + +Then point your mobile application to the `fever.php` address (e.g. `https://freshrss.example.net/api/fever.php`). + +## Compatible clients + +| App | Platform | License | +|:----------------------------------------------------------------------------------:|:-------------------:|:--------------------------------------------------------:| +|[Fluent Reader](https://hyliu.me/fluent-reader/) |Windows, Linux, macOS|[BSD-3-Clause](https://github.com/yang991178/fluent-reader/blob/master/LICENSE)| +|[Readably](https://play.google.com/store/apps/details?id=com.isaiasmatewos.readably)|Android |Closed Source | +|[Fiery Feeds](https://apps.apple.com/app/fiery-feeds-rss-reader/id1158763303) |iOS |Closed Source | +|[Unread](https://apps.apple.com/app/unread-rss-reader/id1252376153) |iOS |Closed Source | +|[Reeder](https://www.reederapp.com/) |iOS |Closed Source | +|[ReadKit](https://apps.apple.com/app/readkit/id588726889) |macOS |Closed Source | + +## Features + +The following features are implemented: + +* fetching categories +* fetching feeds +* fetching RSS items (new, favorites, unread, by_id, by_feed, by_category, since) +* fetching favicons +* setting read marker for item(s) +* setting starred marker for item(s) +* setting read marker for feed +* setting read marker for category +* supports FreshRSS extensions, which use the `entry_before_display` hook + +The following features are not supported: + +* **Hot Links** aka **hot** as there is nothing in FreshRSS yet that is similar or could be used to simulate it. + +## Testing and debugging + +If this API does not work as expected in your RSS reader, you can test it manually with a tool like [Postman](https://www.getpostman.com/). + +Configure a POST request to the URL https://freshrss.example.net/api/fever.php?api which should give you the result: +```json +{ + "api_version": 3, + "auth": 0 +} +``` +Great, the base setup seems to work! + +Now lets try an authenticated call. Fever uses an `api_key`, which is the MD5 hash of `"$username:$apiPassword"`. +Assuming the user is `kevin` and the password `freshrss`, here is a command-line example to compute the resulting `api_key` + +```sh +api_key=`echo -n "kevin:freshrss" | md5sum | cut -d' ' -f1` +``` + +Add a body to your POST request encoded as `form-data` and one key named `api_key` with the value `your-password-hash`: + +```sh +curl -s -F "api_key=$api_key" 'https://freshrss.example.net/api/fever.php?api' +``` + +This should give: +```json +{ + "api_version": 3, + "auth": 1, + "last_refreshed_on_time": "1520013061" +} +``` +Perfect, you're now authenticated and you can start testing the more advanced features. To do so, change the URL and append the possible API actions to your request parameters. Please refer to the [original Fever documentation](https://feedafever.com/api) for more information. + +Some basic calls are: + +* https://freshrss.example.net/api/fever.php?api&items +* https://freshrss.example.net/api/fever.php?api&feeds +* https://freshrss.example.net/api/fever.php?api&groups +* https://freshrss.example.net/api/fever.php?api&unread_item_ids +* https://freshrss.example.net/api/fever.php?api&saved_item_ids +* https://freshrss.example.net/api/fever.php?api&items&since_id=some_id +* https://freshrss.example.net/api/fever.php?api&items&max_id=some_id +* https://freshrss.example.net/api/fever.php?api&mark=item&as=read&id=some_id +* https://freshrss.example.net/api/fever.php?api&mark=item&as=unread&id=some_id + +Replace `some_id` with a real ID from your `freshrss_username_entry` database. + +### Debugging + +If nothing helps and your client is still misbehaving, you can add the following lines to the beginning of the `fever.api` file to determine the cause of the problems: + +```php +file_put_contents(__DIR__ . '/fever.log', $_SERVER['HTTP_USER_AGENT'] . ': ' . json_encode($_REQUEST) . PHP_EOL, FILE_APPEND); +``` + +Then use your RSS client to query the API and afterwards check the file `fever.log`. + +## Credits + +This plugin was inspired by the [tinytinyrss-fever-plugin](https://github.com/dasmurphy/tinytinyrss-fever-plugin). diff --git a/docs/en/developers/06_Reporting_Bugs.md b/docs/en/developers/06_Reporting_Bugs.md new file mode 100644 index 000000000..12d3259a6 --- /dev/null +++ b/docs/en/developers/06_Reporting_Bugs.md @@ -0,0 +1,66 @@ +# Reporting a bug or a suggestion + +Despite the care given to FreshRSS, it's still possible that bugs occur. Development is dynamic, so issues can be corrected quickly. You might also have a feature in mind that doesn't yet exist. Regardless whether your idea seems silly, far-fetched, useless or too specific, please don't hesitate to propose it to us! "Ideas in the air" often find an attentive ear. It's new external perspectives that make the project evolve the most. + +If you're convinced that you should be heard, here's how you can go about it. + +## On GitHub + +GitHub is the ideal platform to submit your requests. It allows us to discuss a problem or suggestion with others and it often generates new ideas. Let's not neglect this "social" aspect! + + 1. [Go to the bug ticket manager](https://github.com/FreshRSS/FreshRSS/issues) + 2. Start by checking if a similar request hasn't already been made. If so, please feel free to add your voice to the request. + 3. If your request is new, [open a new bug ticket](https://github.com/FreshRSS/FreshRSS/issues/new) + 4. Finally, write your request. If you're fluent in English, it's the preferred language because it allows for discussion with the largest number of people. + 5. Please follow the tips below to make it easier to let your ticket be heard. + +## Informal + +Not everyone likes or uses GitHub for a variety of legitimate reasons. That is why you can also contact us in a more informal way. + +* On [our Mattermost chat](https://framateam.org/signup_user_complete/?id=e2680d3e3128b9fac8fdb3003b0024ee) +* On [our subreddit](https://www.reddit.com/r/freshrss/) +* At events / meetings around Free Software +* Over a beer in a bar +* Etc. + +## Tips + +Here are some tips to help you present your bug report or suggestion: + + +* **Pay attention to spelling**. Even if it's not always easy, try your best! +* **Give an explicit title to your request**, even if it's a bit long. This not only helps us understand your request, but also to find your ticket later. +* **One request = one ticket.** You may have lots of ideas while being afraid to spam the bug manager: it doesn't matter. It's better to have a few too many tickets than too many requests in one. We'll close and consolidate requests when possible. +* If you report a bug, think about **providing us with the FreshRSS logs** (accessible in the FreshRSS `data/log/` folder) and the **PHP logs** (the location may vary by distribution, but consider searching in `/var/log/httpd` or `/var/log/apache`). +* If you can't find the log files, specify it in your ticket so we know you've already searched. +* Not all bugs require logs, but if you have any doubts, it is better to provide them to us. Logs are important and very useful for debugging! +* The logs may reveal confidential information, so **be careful not to disclose anything sensitive.** + +In addition, when facing a bug, you're encouraged to follow this message format (from the [Sam & Max website](http://sametmax.com/template-de-demande-daide-en-informatique/): + +### What's my goal? + +Give the general context of what you were trying to do. + +### What have I been trying to do? + +Explain step by step what you have done so that we can reproduce the bug. + +### What results have I achieved? + +The bug: what you see that shouldn't have happened. Here you can provide the logs. + +### What was the expected result? + +So that we understand what you consider to be the problem. + +### What are my circumstances? + +Remember to give the following information if you know it: + + 1. Which browser? Which version? + 2. Which server: Apache, Nginx? Which version? + 3. Which version of PHP? + 4. Which database: SQLite, MySQL, MariaDB, PostgreSQL? Which version? + 5. Which distribution runs on the server? And... which version? |