1. 🚀 Project Overview
2. 📊 QGIS Analytics Dashboard
3. 🚥 QA Status
4. 📖 User Guide
5. 📜 License
6. 📂 Folder Structure
7. 🤖 Using 'AI' (Large Language Models)
8. 🛠️ Tech Stack
9. 🗄️ Data Model
10. 🧊 Using the Nix Shell
11. ✨ Contributing
12. 🙋 Have Questions?
13. 🧑‍💻👩‍💻 Contributors

When a user opens QGIS, their application sends a request to https://feed.qgis.org. The server processes each request and extracts only three key pieces of information:

1. Date (rounded to the nearest day)
2. QGIS Version (the version code of the software)
3. Country (determined from the IP address, but the IP itself is not stored)
4. Operating System (platform string)

This information is then aggregated hourly into three separate tables:

• Daily Country Table:

  • Columns: date, country ISO code, number of hits
  • Example: 2024-06-10, DE, 1200

• Daily QGIS Version Table:

  • Columns: date, QGIS version, number of hits
  • Example: 2024-06-10, 3.34.0, 800

• Daily Platform Table:

  • Columns: date, OS platform, number of hits
  • Example: 2024-06-10, Windows, 900

Each table records the count of requests (hits) for each unique value per day.

• No IP Addresses Stored: The server uses the IP address only to determine the country. The IP is immediately discarded and never stored.

• No Persistent Identifiers: No user IDs, device IDs, or other persistent identifiers are collected or stored.

• Aggregation: Data is stored only as counts per day, per country/version/platform. There is no way to trace data back to an individual user.

• Rate Limiting:

  • Only one hit per IP per hour is counted.
  • Only one opening per day is recorded per user (even if they open/close QGIS multiple times).

• No personal or device information is stored.
• No sharing with third parties.
• Data is only used in aggregate for analytics.

• Users behind NAT or managed networks may be undercounted.
• Users who disable the news feed are not counted.
• Only one hit per IP per hour/day, so heavy users are not overrepresented.

A home page that displays feeds as they are rendered in QGIS is now available at the root of the web server /. Feeds are filterable using the filter widget on the left side. You can directly pass the filter parameters in the url according to the section Available parameters for filters in Endpoint and accepted parameters

Note: When calling the root url from QGIS, the response data is in JSON format. See the section Response data for QGIS in the Endpoint and accepted parameters

The system has three main user roles with different capabilities:

Users with the staff flag can:

• Create new feed entries
• Edit their own entries (including during review)
• Submit entries for review
• Add comments to their entries and respond to reviewer feedback
• View all entries and their statuses

Users with the qgisfeed.publish_qgisfeedentry permission can:

• Review any entry (including their own if they're also the author)
• Approve entries (moves status to "Approved")
• Request changes from authors
• Add comments to any entry
• Publish approved entries

Superusers have all permissions and can:

• Do everything authors and reviewers can do
• Self-approve and publish their own entries
• Manage all system settings

Note: The groups qgisfeedentry_authors and qgisfeedentry_approvers are automatically created when needed.

The review system works similarly to GitHub Pull Requests, enabling collaborative review and discussion:

1. Create Entry (Draft)

   • Author creates a new feed entry
   • Entry starts in "Draft" status
   • Author can assign multiple reviewers

2. Submit for Review

   • Author clicks "Submit for Review"
   • Entry moves to "Pending Review" status
   • Assigned reviewers are notified by email
   • Author can still edit the entry while under review

3. Review Process

   • Reviewers can:
     • ✅ Approve - Entry moves to "Approved" status (ready to publish)
     • ⚠️ Request Changes - Entry moves to "Changes Requested" status
     • 💬 Add Comment - Provide feedback without changing status
   • Multiple reviewers can be assigned
   • Each reviewer's status is tracked independently
   • Authors can respond with comments at any time

4. Addressing Feedback

   • Author makes requested changes
   • Entry stays in review state (doesn't reset)
   • Reviewers are notified of updates
   • Review conversation continues

5. Approval

   • Any one reviewer approval moves entry to "Approved" status
   • No need to wait for all reviewers
   • Multiple approvals are visible but not required

6. Publishing

   • Only users with publish permission can publish
   • Authors without publish permission cannot publish (even their own entries)
   • Authors with publish permission can self-approve and publish
   • Entry moves to "Published" status and goes live

Draft → Pending Review → Approved → Published
           ↓
    Changes Requested → (back to Pending Review)

• Review History: All actions are visible in chronological order (oldest first)
• Comments: Both authors and reviewers can add comments at any time
• Status Badges: Visual indicators show each reviewer's current state:
  • ✅ Green: Approved
  • ⚠️ Yellow: Changes Requested
  • 💬 Blue: Comment Only
  • ⏰ Gray: Pending (not reviewed yet)

• Multiple reviewers can be assigned to one entry
• Reviewers are visible throughout the entire workflow
• Each reviewer's status is tracked and displayed separately
• Authors can see who has approved and who is still pending

After logging in at /accounts/login/ (accessible from the Login button on the Homepage), users can manage feed items:

• View a list of all feed items
• Sort and filter by: title, date published, author, language, review status
• Create new feed items (click "New entry" button)
• Edit existing entries (click on any item in the list)
• See entry status badges (Draft, Pending Review, Changes Requested, Approved, Published)

• Left side: Edit form with all entry fields
• Right side: Live preview showing how it will appear in QGIS
• Changes update the preview in real-time

• Available on both create and edit forms
• Select multiple reviewers using the dropdown
• Reviewers are notified by email when assigned

Shows the current state of each assigned reviewer:

• Name and review status (Pending, Approved, Changes Requested)
• Timestamp of their last action
• Color-coded visual indicators

• Rich text editor with limited HTML tags: <p>, <strong>, <em>
• Character limit is configurable (default: 500 characters)
• Live character counter

For Authors:

• Save as draft
• Submit for review
• Edit during review (stays in review state)
• Add comments for reviewers

For Reviewers:

• Approve entry
• Request changes
• Add comments
• Publish (if approved)

For Authors with Publish Permission:

• All author actions
• All reviewer actions (can self-approve and publish)

• Visible when entry is under review, has changes requested, or is approved
• Shows all review history in chronological order
• Authors can add comments at any time
• Reviewers can approve, request changes, or comment
• Comment field is always available for both parties

The application has a single endpoint available at the web server root / the reponse is in JSON format.

Example call: http://localhost:8000/

Returned data:

[
  {
    "pk": 1,
    "title": "QGIS acquired by ESRI",
    "image": "http://localhost:8000/media/feedimages/image.png",
    "content": "<p>QGIS is finally part of the ESRI ecosystem, it has been rebranded as CrashGIS to better integrate with ESRI products line.</p>",
    "url": "https://www.qgis.com",
    "sticky": true,
    "publish_from": 1557419128
  },
  {
    "pk": 2,
    "title": "Null Island QGIS Meeting",
    "image": "",
    "content": "<p>Let's dive in the ocean together!</p>",
    "url": null,
    "sticky": false,
    "publish_from": 1557419128
  },
  {
    "pk": 3,
    "title": "QGIS Italian Meeting",
    "image": "",
    "content": "<p>Ciao from Italy!</p>",
    "url": null,
    "sticky": false,
    "publish_from": 1557419128
  }
]

The following parameters can be passed by the client to filter available records.

Parameters are validated and in case they are not valid a Bad Request HTTP error code 400 is returned.

When after is passed, only the records that have been published after the given value will be returned.

Accepted values: unix timestamp (UTC)

Example call: http://localhost:8000/?after=1557419013

When lang is passed, you can specify one or more language codes as a comma-separated list. Only records with a matching lang or null lang will be returned; records with non-matching languages are excluded.

Accepted values: Comma-separated list of ISO-639-1 two-letter language codes

Example call: http://localhost:8000/?lang=de,fr,it

When lat and lon are passed, the records that have a location filter set will be returned only if the point defined by lat and lon is within record's location.

Accepted values: ESPG:4326 latitude and longitude

Example call: http://localhost:8000/?lat=44.5&lon=9.23