Compare commits

..
Author SHA1 Message Date
shamoon b1cb8a8365 Open release notes from the version link now 2026-11-18 11:12:53 -08:00
shamoon 423e63b3d0 Pill love 2026-11-18 10:55:02 -08:00
shamoon bd67bbea29 Fix the tour outro thing by keepign the li around 2026-11-18 10:45:11 -08:00
shamoon 031d565d0e Swap whats new for docs in slim sidebar 2026-11-18 10:23:37 -08:00
shamoon 657dd5365f Dont steal focus 2026-11-18 10:19:28 -08:00
shamoon 2e515ae4f8 Ahh, better star buttons 2026-11-18 10:13:12 -08:00
shamoon 1a2ab96ddc tests 2026-11-18 10:08:26 -08:00
shamoon ad6ea30d0d Fix tests 2026-11-18 10:08:21 -08:00
shamoon df30b75c61 oops actually use the cache 2026-11-18 10:07:06 -08:00
shamoon 0fc148d755 Split button 2026-11-18 10:04:42 -08:00
shamoon a5aa92519b Use the stars 2026-11-18 10:02:46 -08:00
shamoon 6cffa8cb91 fetch the stars, yes really 2026-11-18 09:55:33 -08:00
shamoon 908a4d6217 Work the star button 2026-11-18 09:46:04 -08:00
shamoon 4da1f36403 support link, all releases 2026-11-18 09:30:45 -08:00
shamoon 06a6c2887c Shameless plug 2026-11-18 09:26:30 -08:00
shamoon 5fae2c240f I see you Sonar 2026-11-18 09:23:53 -08:00
shamoon f3ee22c548 reuse the gh link 2026-11-18 09:23:53 -08:00
shamoon 0d2625e4ac Some typography love 2026-11-18 09:23:53 -08:00
shamoon 1ac12b9fa4 Add date, tidy up link out 2026-11-18 09:08:50 -08:00
shamoon 7af74a9746 Add links for each release 2026-11-18 08:57:29 -08:00
shamoon f482fd6c3c Do some cleanup of GH html 2026-11-18 08:48:26 -08:00
shamoon 084a3b1cb8 Crap, lets use GH html instead 2026-11-18 08:41:39 -08:00
shamoon a1a2eb5b36 Drop some release sections 2026-11-18 08:37:36 -08:00
shamoon fb4e644df7 It works! Not pretty tho 2026-11-18 08:29:52 -08:00
shamoon 1356da49ae Generalize our markdown pipe 2026-11-18 08:08:03 -08:00
shamoon ef1a0f0166 Obsessing over styling a bit 2026-11-17 23:50:41 -08:00
shamoon da5d1780d9 Better visual New 2026-11-17 23:37:19 -08:00
shamoon a127ecd35d New button, TODO release notes modal 2026-11-17 23:35:04 -08:00
shamoon 068fc4b8bc This is better as a signal 2026-11-17 23:27:21 -08:00
shamoon e7a4367540 WHATS_NEW_LAST_SEEN_VERSION setting, seeding, updating 2026-11-17 23:20:39 -08:00
shamoon 9f57da5193 Version compare util from ChatGPT 2026-11-17 23:14:30 -08:00
shamoon c091766a86 Frontend getReleaseNotes 2026-11-17 23:03:13 -08:00
shamoon ffe042e5ba 1h seems fine 2026-11-17 22:59:07 -08:00
shamoon 7f10b918ae Tests 2026-11-17 22:40:08 -08:00
shamoon c944aaedd3 add the schema stuff 2026-11-17 22:36:19 -08:00
shamoon 45dac15aef now the release notes view 2026-11-17 22:32:49 -08:00
shamoon d6c18ac04d Actually cache it longer and tie it to the current version 2026-11-17 22:30:05 -08:00
shamoon 3921311901 Use it in remote version view 2026-11-17 22:26:23 -08:00
shamoon 3dc86ba484 Move to a get_github_releases helper we can share 2026-11-17 22:25:55 -08:00
28 changed files with 1104 additions and 138 deletions

No files matched your search

@@ -361,8 +361,9 @@
</a>
</li>
}
<li class="nav-item mt-2 position-relative" [class.d-none]="settingsService.sidebarItemIsHidden(HideableSidebarItemID.Documentation) && !settingsService.organizingSidebarItems()" tourAnchor="tour.outro">
<a class="text-muted small d-flex align-items-center flex-wrap text-decoration-none nav-anchor" [class.opacity-50]="settingsService.sidebarItemIsHidden(HideableSidebarItemID.Documentation)" [class.pe-5]="settingsService.organizingSidebarItems() && !slimSidebarEnabled && !slimSidebarAnimating()"
<li class="nav-item mt-2 position-relative" [class.d-none]="settingsService.sidebarItemIsHidden(HideableSidebarItemID.Documentation) && !settingsService.organizingSidebarItems()"
[class.d-md-block]="slimSidebarEnabled && settingsService.unseenReleasesSince()" tourAnchor="tour.outro">
<a class="text-muted small d-flex align-items-center flex-wrap text-decoration-none nav-anchor" [class.d-md-none]="slimSidebarEnabled && settingsService.unseenReleasesSince()" [class.opacity-50]="settingsService.sidebarItemIsHidden(HideableSidebarItemID.Documentation)" [class.pe-5]="settingsService.organizingSidebarItems() && !slimSidebarEnabled && !slimSidebarAnimating()"
target="_blank" rel="noopener noreferrer" href="https://docs.paperless-ngx.com" ngbPopover="Documentation"
i18n-ngbPopover [disablePopover]="!slimSidebarPopoversEnabled" placement="end" container="body"
triggers="mouseenter:mouseleave" popoverClass="popover-slim">
@@ -371,16 +372,26 @@
@if (settingsService.organizingSidebarItems()) {
<pngx-input-switch class="position-absolute top-50 end-0 translate-middle-y me-1" [class.d-none]="slimSidebarEnabled || slimSidebarAnimating()" [compact]="true" title="Documentation" i18n-title [ngModel]="!settingsService.sidebarItemIsHidden(HideableSidebarItemID.Documentation)" (ngModelChange)="toggleSidebarItem(HideableSidebarItemID.Documentation, $event)"></pngx-input-switch>
}
@if (slimSidebarEnabled && settingsService.unseenReleasesSince()) {
<button type="button" class="btn btn-link border-0 w-100 text-muted small d-none d-md-flex align-items-center nav-anchor position-relative" (click)="showReleaseNotes()"
aria-label="See what's new in this version" i18n-aria-label
ngbPopover="What's new" i18n-ngbPopover placement="end" container="body"
triggers="mouseenter:mouseleave" popoverClass="popover-slim">
<pngx-bs-icon class="d-flex" name="info-circle"></pngx-bs-icon>
<div class="position-absolute top-0 start-50 ms-1 p-1 bg-success rounded-circle"></div>
</button>
}
</li>
<li class="nav-item" [class.visually-hidden]="slimSidebarEnabled">
<div class="text-muted small d-flex align-items-center flex-wrap nav-label">
<div class="me-2">
<a class="text-muted text-decoration-none" target="_blank" rel="noopener noreferrer"
href="https://github.com/paperless-ngx/paperless-ngx" ngbPopover="GitHub" i18n-ngbPopover
[disablePopover]="!slimSidebarPopoversEnabled" placement="end" container="body"
triggers="mouseenter:mouseleave" popoverClass="popover-slim">
<button type="button" class="bg-transparent border-0 p-0 text-muted" (click)="showReleaseNotes()" title="See what's new in this version" i18n-title>
{{ versionString }}
</a>
</button>
@if (settingsService.unseenReleasesSince()) {
<button type="button" class="btn btn-whats-new rounded-pill smaller ms-1 py-1 px-2 fw-bold lh-sm align-baseline" (click)="showReleaseNotes()"
title="See what's new in this version" i18n-title i18n>New</button>
}
</div>
@if (!settingsService.updateCheckingIsSet || appRemoteVersion()) {
<div class="version-check d-flex align-items-center">
@@ -700,3 +700,15 @@ main {
.smaller {
font-size: 0.75rem;
}
// From active / hover of sidebar nav links
.btn-whats-new {
--bs-btn-color: var(--bs-primary);
--bs-btn-bg: color-mix(in srgb, var(--bs-primary) 13%, transparent);
--bs-btn-border-width: 0;
--bs-btn-font-weight: 600;
--bs-btn-hover-color: var(--bs-primary);
--bs-btn-hover-bg: color-mix(in srgb, var(--bs-primary) 20%, transparent);
--bs-btn-active-color: var(--bs-primary);
--bs-btn-active-bg: color-mix(in srgb, var(--bs-primary) 20%, transparent);
}
@@ -42,6 +42,7 @@ import { environment } from 'src/environments/environment'
import { ProfileEditDialogComponent } from '../common/profile-edit-dialog/profile-edit-dialog.component'
import { UploadStatusTrayComponent } from '../common/upload-status-tray/upload-status-tray.component'
import { DocumentDetailComponent } from '../document-detail/document-detail.component'
import { ReleaseNotesDialogComponent } from '../common/release-notes-dialog/release-notes-dialog.component'
import { AppFrameComponent } from './app-frame.component'
import { GlobalSearchComponent } from './global-search/global-search.component'
@@ -695,6 +696,68 @@ describe('AppFrameComponent', () => {
expect(maybeRefreshSpy).toHaveBeenCalled()
})
it('should show new release pill and mark releases seen on click', () => {
settingsService.set(SETTINGS_KEYS.VERSION, '3.5.1')
settingsService.set(SETTINGS_KEYS.WHATS_NEW_LAST_SEEN_VERSION, '3.4.2')
fixture.detectChanges()
const pill = fixture.debugElement
.queryAll(By.css('button'))
.find((b) => b.nativeElement.textContent.trim() === 'New')
expect(pill).toBeTruthy()
pill.nativeElement.click()
const req = httpTestingController.expectOne(
`${environment.apiBaseUrl}ui_settings/`
)
expect(req.request.body.settings.whats_new.last_seen_version).toEqual(
'3.5.1'
)
req.flush({ success: true })
fixture.detectChanges()
expect(
fixture.debugElement
.queryAll(By.css('button'))
.find((b) => b.nativeElement.textContent.trim() === 'New')
).toBeUndefined()
})
it('should open current release notes from the version without marking seen', () => {
settingsService.set(SETTINGS_KEYS.VERSION, '3.5.1')
settingsService.set(SETTINGS_KEYS.WHATS_NEW_LAST_SEEN_VERSION, '3.5.1')
fixture.detectChanges()
const modalSpy = jest.spyOn(modalService, 'open')
const versionButton = fixture.debugElement
.queryAll(By.css('button'))
.find((b) => b.nativeElement.textContent.includes('3.5.1'))
versionButton.nativeElement.click()
expect(modalSpy).toHaveBeenCalledWith(
ReleaseNotesDialogComponent,
expect.anything()
)
httpTestingController.expectNone(`${environment.apiBaseUrl}ui_settings/`)
})
it('should show new release dot instead of documentation in slim sidebar', () => {
settingsService.set(SETTINGS_KEYS.SLIM_SIDEBAR, true)
settingsService.set(SETTINGS_KEYS.VERSION, '3.5.1')
settingsService.set(SETTINGS_KEYS.WHATS_NEW_LAST_SEEN_VERSION, '3.4.2')
fixture.detectChanges()
const whatsNew = fixture.debugElement.query(
By.css('button[aria-label="See what\'s new in this version"]')
).nativeElement
const docs = fixture.debugElement.query(
By.css('a[href="https://docs.paperless-ngx.com"].nav-anchor')
).nativeElement
expect(docs.classList).toContain('d-md-none')
// both share one li so the tour anchor points at whichever is shown
expect(whatsNew.closest('li')).toBe(docs.closest('li'))
})
it('should show tasks badge for needs-attention tasks', () => {
jest
.spyOn(tasksService, 'needsAttentionTasksCount', 'get')
@@ -68,6 +68,7 @@ import { SwitchComponent } from '../common/input/switch/switch.component'
import { BrandMarkComponent } from '../common/logo/brand-mark/brand-mark.component'
import { LogoComponent } from '../common/logo/logo.component'
import { ProfileEditDialogComponent } from '../common/profile-edit-dialog/profile-edit-dialog.component'
import { ReleaseNotesDialogComponent } from '../common/release-notes-dialog/release-notes-dialog.component'
import { UploadStatusTrayComponent } from '../common/upload-status-tray/upload-status-tray.component'
import { DocumentDetailComponent } from '../document-detail/document-detail.component'
import { ComponentWithPermissions } from '../with-permissions/with-permissions.component'
@@ -551,6 +552,21 @@ export class AppFrameComponent
})
}
showReleaseNotes() {
const since = this.settingsService.unseenReleasesSince()
const modal = this.modalService.open(ReleaseNotesDialogComponent, {
size: 'lg',
scrollable: true,
})
modal.componentInstance.load(since)
if (since) {
this.settingsService
.markReleasesSeen()
.pipe(first())
.subscribe({ error: () => {} })
}
}
setUpdateChecking(enable: boolean) {
this.settingsService.set(SETTINGS_KEYS.UPDATE_CHECKING_ENABLED, enable)
this.settingsService
@@ -87,6 +87,7 @@ import folderFill from 'bootstrap-icons/icons/folder-fill.svg'
import folder from 'bootstrap-icons/icons/folder.svg'
import funnel from 'bootstrap-icons/icons/funnel.svg'
import gear from 'bootstrap-icons/icons/gear.svg'
import github from 'bootstrap-icons/icons/github.svg'
import globe2 from 'bootstrap-icons/icons/globe2.svg'
import google from 'bootstrap-icons/icons/google.svg'
import grid from 'bootstrap-icons/icons/grid.svg'
@@ -249,6 +250,7 @@ export const icons: Record<string, string> = {
folderFill,
funnel,
gear,
github,
globe2,
google,
grid,
@@ -1,90 +0,0 @@
import { provideHttpClient } from '@angular/common/http'
import { provideHttpClientTesting } from '@angular/common/http/testing'
import { Component } from '@angular/core'
import { ComponentFixture, TestBed } from '@angular/core/testing'
import { FormControl, ReactiveFormsModule } from '@angular/forms'
import { NumberComponent } from './number/number.component'
import { TextComponent } from './text/text.component'
import { TextAreaComponent } from './textarea/textarea.component'
import { UrlComponent } from './url/url.component'
@Component({
imports: [
ReactiveFormsModule,
TextComponent,
NumberComponent,
TextAreaComponent,
UrlComponent,
],
template: `
<pngx-input-text [formControl]="control" />
<pngx-input-number [formControl]="control" [showAdd]="false" />
<pngx-input-textarea [formControl]="control" />
<pngx-input-url [formControl]="control" />
`,
})
class InputEventsHostComponent {
control = new FormControl<string | number | null>(null)
}
describe.each([
['text', 'pngx-input-text input', 'Edited text', 'Edited text'],
['number', 'pngx-input-number input', '42', 42],
['textarea', 'pngx-input-textarea textarea', 'Edited\ntext', 'Edited\ntext'],
['url', 'pngx-input-url input', 'https://example.com', 'https://example.com'],
])(
'%s input events',
(_type, selector: string, text: string, value: string | number) => {
let fixture: ComponentFixture<InputEventsHostComponent>
let control: FormControl<string | number | null>
let input: HTMLInputElement | HTMLTextAreaElement
beforeEach(() => {
TestBed.configureTestingModule({
imports: [InputEventsHostComponent],
providers: [provideHttpClient(), provideHttpClientTesting()],
})
fixture = TestBed.createComponent(InputEventsHostComponent)
control = fixture.componentInstance.control
})
async function render() {
fixture.detectChanges()
await fixture.whenStable()
input = fixture.nativeElement.querySelector(selector)
}
it('updates the form while typing and marks it touched only on blur', async () => {
await render()
const changed = jest.fn()
control.valueChanges.subscribe(changed)
input.value = text
input.dispatchEvent(new Event('input'))
expect(control.value).toBe(value)
expect(control.dirty).toBe(true)
expect(control.touched).toBe(false)
input.dispatchEvent(new Event('change'))
input.dispatchEvent(new Event('blur'))
expect(control.touched).toBe(true)
expect(changed).toHaveBeenCalledTimes(1)
})
it('honors an explicit updateOn blur strategy', async () => {
control = new FormControl<string | number | null>(null, {
updateOn: 'blur',
})
fixture.componentInstance.control = control
await render()
input.value = text
input.dispatchEvent(new Event('input'))
expect(control.value).toBeNull()
expect(control.pristine).toBe(true)
input.dispatchEvent(new Event('blur'))
expect(control.value).toBe(value)
expect(control.dirty).toBe(true)
expect(control.touched).toBe(true)
})
}
)
@@ -12,7 +12,7 @@
</div>
<div class="position-relative" [class.col-md-9]="horizontal">
<div class="input-group" [class.is-invalid]="error">
<input #inputField type="number" class="form-control" [step]="step" [id]="inputId" [(ngModel)]="value" [ngModelOptions]="{standalone: true}" (ngModelChange)="onChange($event)" (blur)="onTouched()" [class.is-invalid]="error" [disabled]="disabled">
<input #inputField type="number" class="form-control" [step]="step" [id]="inputId" [(ngModel)]="value" [ngModelOptions]="{standalone: true}" (change)="onChange(value)" [class.is-invalid]="error" [disabled]="disabled">
@if (showAdd) {
<button class="btn btn-outline-secondary" type="button" id="button-addon1" (click)="nextAsn()" [disabled]="disabled">+1</button>
}
@@ -11,7 +11,7 @@
}
</div>
<div class="position-relative" [class.col-md-9]="horizontal">
<input #inputField type="text" class="form-control" [class.is-invalid]="error" [id]="inputId" [(ngModel)]="value" [ngModelOptions]="{standalone: true}" (ngModelChange)="onChange($event)" (blur)="onTouched()" [disabled]="disabled" [autocomplete]="autocomplete" [placeholder]="placeholder">
<input #inputField type="text" class="form-control" [class.is-invalid]="error" [id]="inputId" [(ngModel)]="value" [ngModelOptions]="{standalone: true}" (change)="onChange(value)" [disabled]="disabled" [autocomplete]="autocomplete" [placeholder]="placeholder">
@if (hint) {
<small class="form-text text-muted" [innerHTML]="hint"></small>
}
@@ -18,8 +18,7 @@
[class.font-monospace]="monospace"
[(ngModel)]="value"
[ngModelOptions]="{standalone: true}"
(ngModelChange)="onChange($event)"
(blur)="onTouched()"
(change)="onChange(value)"
[disabled]="disabled"
[placeholder]="placeholder"
rows="4">
@@ -10,7 +10,7 @@
</div>
<div [class.col-md-9]="horizontal">
<div class="input-group" [class.is-invalid]="error">
<input #inputField type="url" class="form-control" [class.is-invalid]="error" placeholder="https://" [id]="inputId" [(ngModel)]="value" [ngModelOptions]="{standalone: true}" (ngModelChange)="onChange($event)" (blur)="onTouched()" [disabled]="disabled">
<input #inputField type="url" class="form-control" [class.is-invalid]="error" placeholder="https://" [id]="inputId" [(ngModel)]="value" [ngModelOptions]="{standalone: true}" (change)="onChange(value)" [disabled]="disabled">
<a class="btn btn-outline-secondary rounded-end" title="Open link" i18n-title [href]="value" target="_blank">
<pngx-bs-icon width="1.2em" height="1.2em" name="box-arrow-up-right"></pngx-bs-icon>
</a>
@@ -0,0 +1,71 @@
<div class="modal-header">
<div>
<h4 class="modal-title" i18n>What's new in Paperless-ngx</h4>
@if (since()) {
<p class="text-muted small mb-0" i18n>Updated from {{ since() }} to {{ version }}</p>
}
</div>
<div class="d-flex align-items-center gap-3 ms-auto">
<div class="btn-group btn-group-sm" role="group">
<a tabindex="-1" class="btn btn-dark border-dark-subtle d-flex align-items-center" [href]="repoUrl" target="_blank" rel="noopener noreferrer"
title="Star Paperless-ngx on GitHub" i18n-title>
<pngx-bs-icon name="github" class="me-1 d-flex" width="12" height="12"></pngx-bs-icon><span class="small" i18n>Star</span>
</a>
@if (stars() !== null) {
<a tabindex="-1" class="btn btn-dark border-dark-subtle d-flex align-items-center" [href]="repoUrl + '/stargazers'" target="_blank" rel="noopener noreferrer"
title="Stargazers" i18n-title>
<span class="small">{{ stars() | number }}</span>
</a>
}
</div>
<button type="button" class="btn-close m-0" aria-label="Close" i18n-aria-label (click)="close()"></button>
</div>
</div>
<div class="modal-body">
@if (!updateCheckingEnabled) {
<p class="mb-0" i18n>Release notes are fetched from GitHub when update checking is enabled.</p>
<ng-container *ngTemplateOutlet="githubLink"></ng-container>
} @else if (loading()) {
<div class="d-flex align-items-center gap-2 text-muted">
<output class="spinner-border spinner-border-sm"></output>
<ng-container i18n>Loading release notes...</ng-container>
</div>
} @else if (!releases()?.length) {
<p class="mb-0" i18n>Release notes could not be loaded.</p>
<ng-container *ngTemplateOutlet="githubLink"></ng-container>
} @else {
@for (release of releases(); track release.version) {
<section class="release-notes" [class.border-top]="!$first" [class.pt-3]="!$first" [class.mt-3]="!$first">
<div class="d-flex align-items-baseline gap-2 mb-2">
<h5 class="mb-0">{{ release.version }}</h5>
<a class="d-flex flex-row align-items-center text-secondary btn-link" [href]="release.html_url" target="_blank" rel="noopener noreferrer"
title="View on GitHub" i18n-title>
@if (release.published_at) {
<span class="text-muted small me-2">{{ release.published_at | customDate }}</span>
}
<pngx-bs-icon name="box-arrow-up-right" class="mt-n1" width=".7rem"></pngx-bs-icon>
</a>
</div>
<div class="release-notes-body" [innerHTML]="release.body_html"></div>
</section>
}
}
</div>
<div class="modal-footer justify-content-between">
<div class="d-flex flex-wrap gap-3 small">
<a class="link-secondary text-decoration-none d-flex align-items-center" [href]="releasesUrl" target="_blank" rel="noopener noreferrer">
<pngx-bs-icon name="clock-history" class="me-1"></pngx-bs-icon><ng-container i18n>All releases</ng-container>
</a>
<a class="link-secondary text-decoration-none d-flex align-items-center" [href]="discussionsUrl" target="_blank" rel="noopener noreferrer">
<pngx-bs-icon name="chat-left-text" class="me-1"></pngx-bs-icon><ng-container i18n>Need support? Ask in Discussions</ng-container>
</a>
</div>
<button type="button" class="btn btn-outline-secondary" (click)="close()" i18n>Close</button>
</div>
<ng-template #githubLink>
<a class="small" [href]="releaseUrl" target="_blank" rel="noopener noreferrer">
<ng-container i18n>View on GitHub</ng-container>
<pngx-bs-icon name="box-arrow-up-right" class="ms-1"></pngx-bs-icon>
</a>
</ng-template>
@@ -0,0 +1,77 @@
// Styles for GitHub-rendered release notes (body_html)
:host ::ng-deep .release-notes-body {
// Repeats the version heading
> h2:first-child {
display: none;
}
// Section labels e.g. "Bug Fixes"
> h3 {
color: var(--bs-secondary-color);
font-size: 0.875rem;
font-weight: 600;
margin-top: 1rem;
margin-bottom: 0.375rem;
}
ul {
padding-left: 1.25rem;
margin-bottom: 0.75rem;
}
li {
margin-bottom: 0.25rem;
&::marker {
color: var(--bs-secondary-color);
}
}
a {
text-decoration: none;
&:hover {
text-decoration: underline;
}
}
a.user-mention {
color: var(--bs-secondary-color);
}
details {
margin-bottom: 0.75rem;
> summary {
color: var(--bs-secondary-color);
font-size: 0.875rem;
cursor: pointer;
margin-bottom: 0.375rem;
}
}
// Keep the link underline off code, where it hides underscores
// e.g. PAPERLESS_ALLOWED_HOSTS
a code {
display: inline-block;
}
// GitHub alerts, e.g. > [!NOTE]
.markdown-alert {
background-color: color-mix(in srgb, var(--bs-primary) 8%, transparent);
border-left: 0.25rem solid var(--bs-primary);
border-radius: var(--bs-border-radius);
padding: 0.75rem 1rem;
margin-bottom: 1rem;
> :last-child {
margin-bottom: 0;
}
}
.markdown-alert-title {
color: var(--bs-primary);
font-weight: 600;
margin-bottom: 0.25rem;
}
}
@@ -0,0 +1,131 @@
import { DatePipe } from '@angular/common'
import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http'
import {
HttpTestingController,
provideHttpClientTesting,
} from '@angular/common/http/testing'
import { ComponentFixture, TestBed } from '@angular/core/testing'
import { NgbActiveModal } from '@ng-bootstrap/ng-bootstrap'
import { SETTINGS_KEYS } from 'src/app/data/ui-settings'
import { SettingsService } from 'src/app/services/settings.service'
import { environment } from 'src/environments/environment'
import {
prepareReleaseHtml,
ReleaseNotesDialogComponent,
} from './release-notes-dialog.component'
describe('ReleaseNotesDialogComponent', () => {
let component: ReleaseNotesDialogComponent
let fixture: ComponentFixture<ReleaseNotesDialogComponent>
let httpTestingController: HttpTestingController
let settingsService: SettingsService
function create(updateCheckingEnabled: boolean) {
settingsService = TestBed.inject(SettingsService)
settingsService.set(SETTINGS_KEYS.VERSION, '3.5.1')
settingsService.set(
SETTINGS_KEYS.UPDATE_CHECKING_ENABLED,
updateCheckingEnabled
)
fixture = TestBed.createComponent(ReleaseNotesDialogComponent)
component = fixture.componentInstance
}
beforeEach(() => {
TestBed.configureTestingModule({
imports: [ReleaseNotesDialogComponent],
providers: [
DatePipe,
NgbActiveModal,
provideHttpClient(withInterceptorsFromDi()),
provideHttpClientTesting(),
],
})
httpTestingController = TestBed.inject(HttpTestingController)
})
afterEach(() => {
httpTestingController.verify()
})
it('should load and render release notes since a version', () => {
create(true)
component.load('3.4.2')
const req = httpTestingController.expectOne(
`${environment.apiBaseUrl}release_notes/?since=3.4.2`
)
req.flush({
version: '3.5.1',
releases: [
{
version: '3.5.1',
name: 'Paperless-ngx v3.5.1',
body_html:
'<h2>paperless-ngx 3.5.1</h2><h3>Bug Fixes</h3><ul><li>Fix: a thing</li></ul>' +
'<h3>All App Changes</h3><details><summary>1 change</summary><ul><li>Fix: a thing</li></ul></details>',
html_url: '',
published_at: '2026-11-18T05:22:01Z',
},
],
})
fixture.detectChanges()
const text = fixture.nativeElement.textContent
expect(text).toContain('Updated from 3.4.2 to 3.5.1')
expect(text).toContain('Bug Fixes')
expect(
fixture.nativeElement.querySelector('.release-notes-body details summary')
.textContent
).toEqual('1 change')
})
it('should open release note links safely and drop svg icons', () => {
const html = prepareReleaseHtml(
'<div class="markdown-alert"><p class="markdown-alert-title"><svg><path d="M0"></path></svg>Note</p></div>' +
'<p><a href="https://github.com/paperless-ngx/paperless-ngx/pull/1" data-hovercard-type="pull_request">#1</a></p>'
)
const doc = new DOMParser().parseFromString(html, 'text/html')
expect(doc.querySelector('svg')).toBeNull()
expect(doc.querySelector('.markdown-alert-title').textContent).toEqual(
'Note'
)
const link = doc.querySelector('a')
expect(link.getAttribute('target')).toEqual('_blank')
expect(link.getAttribute('rel')).toEqual('noopener noreferrer nofollow')
expect(link.hasAttribute('data-hovercard-type')).toBe(false)
})
it('should show a message if release notes could not be loaded', () => {
create(true)
component.load(null)
httpTestingController
.expectOne(`${environment.apiBaseUrl}release_notes/`)
.flush('error', { status: 500, statusText: 'error' })
fixture.detectChanges()
expect(fixture.nativeElement.textContent).toContain(
'Release notes could not be loaded'
)
})
it('should not fetch release notes if update checking is disabled', () => {
create(false)
component.load('3.4.2')
fixture.detectChanges()
httpTestingController.expectNone(`${environment.apiBaseUrl}release_notes/`)
expect(fixture.nativeElement.textContent).toContain(
'when update checking is enabled'
)
expect(component.releaseUrl).toEqual(
'https://github.com/paperless-ngx/paperless-ngx/releases/tag/v3.5.1'
)
})
it('should support close', () => {
create(false)
const closeSpy = jest.spyOn(component.activeModal, 'close')
component.close()
expect(closeSpy).toHaveBeenCalled()
})
})
@@ -0,0 +1,103 @@
import { DecimalPipe, NgTemplateOutlet } from '@angular/common'
import { Component, inject, signal } from '@angular/core'
import { NgbActiveModal } from '@ng-bootstrap/ng-bootstrap'
import { first } from 'rxjs'
import { BootstrapIconComponent } from 'src/app/components/common/bootstrap-icon/bootstrap-icon.component'
import { SETTINGS_KEYS } from 'src/app/data/ui-settings'
import { CustomDatePipe } from 'src/app/pipes/custom-date.pipe'
import {
AppRelease,
RemoteVersionService,
} from 'src/app/services/rest/remote-version.service'
import { SettingsService } from 'src/app/services/settings.service'
const REPO_URL = 'https://github.com/paperless-ngx/paperless-ngx'
const RELEASES_URL = `${REPO_URL}/releases`
const DISCUSSIONS_URL = `${REPO_URL}/discussions/new/choose`
/**
* Tweak GitHub release HTML: open links in a new tab, add no referrer etc,
* drop inline svgs and GH `data-*` attributes. Angular sanitizes all of this anyway.
*/
export function prepareReleaseHtml(html: string): string {
const doc = new DOMParser().parseFromString(html, 'text/html')
doc.querySelectorAll('svg').forEach((svg) => svg.remove())
doc.body.querySelectorAll('*').forEach((el) => {
for (const attr of Array.from(el.attributes)) {
if (attr.name.startsWith('data-')) el.removeAttribute(attr.name)
}
})
doc.querySelectorAll('a').forEach((a) => {
a.setAttribute('target', '_blank')
a.setAttribute('rel', 'noopener noreferrer nofollow')
})
return doc.body.innerHTML
}
@Component({
selector: 'pngx-release-notes-dialog',
templateUrl: './release-notes-dialog.component.html',
styleUrls: ['./release-notes-dialog.component.scss'],
imports: [
BootstrapIconComponent,
CustomDatePipe,
NgTemplateOutlet,
DecimalPipe,
],
})
export class ReleaseNotesDialogComponent {
readonly activeModal = inject(NgbActiveModal)
private readonly remoteVersionService = inject(RemoteVersionService)
private readonly settingsService = inject(SettingsService)
readonly since = signal<string | null>(null)
readonly releases = signal<AppRelease[] | null>(null)
readonly stars = signal<number | null>(null)
readonly loading = signal(false)
readonly version: string = this.settingsService.get(SETTINGS_KEYS.VERSION)
readonly updateCheckingEnabled: boolean = this.settingsService.get(
SETTINGS_KEYS.UPDATE_CHECKING_ENABLED
)
readonly repoUrl = REPO_URL
readonly releasesUrl = RELEASES_URL
readonly discussionsUrl = DISCUSSIONS_URL
get releaseUrl(): string {
return this.version ? `${RELEASES_URL}/tag/v${this.version}` : RELEASES_URL
}
/**
* Load notes for releases after `since`, or the running version's
* notes if `since` is null.
*/
load(since: string | null): void {
this.since.set(since)
if (!this.updateCheckingEnabled) return
this.loading.set(true)
this.remoteVersionService
.getReleaseNotes(since ?? undefined)
.pipe(first())
.subscribe({
next: (notes) => {
this.releases.set(
notes.releases.map((release) => ({
...release,
body_html: prepareReleaseHtml(release.body_html),
}))
)
this.stars.set(notes.stars ?? null)
this.loading.set(false)
},
error: () => {
this.releases.set([])
this.loading.set(false)
},
})
}
close(): void {
this.activeModal.close()
}
}
@@ -390,12 +390,14 @@ describe('DocumentDetailComponent', () => {
expect(component.documentForm.get('title').value).toEqual('Foo Bar')
})
it('should update the title form value without waiting for debounce or blur', () => {
it('should update title before doc change if was not updated via debounce', () => {
jest.useFakeTimers()
initNormally()
const input = component.titleInput.inputField.nativeElement
input.value = 'Foo Bar'
input.dispatchEvent(new Event('input'))
component.titleInput.value = 'Foo Bar'
component.titleInput.inputField.nativeElement.dispatchEvent(
new Event('change')
)
jest.advanceTimersByTime(1000)
expect(component.documentForm.get('title').value).toEqual('Foo Bar')
})
+6
View File
@@ -75,6 +75,7 @@ export const SETTINGS_KEYS = {
UPDATE_CHECKING_ENABLED: 'general-settings:update-checking:enabled',
UPDATE_CHECKING_BACKEND_SETTING:
'general-settings:update-checking:backend-setting',
WHATS_NEW_LAST_SEEN_VERSION: 'general-settings:whats-new:last-seen-version',
SAVED_VIEWS_WARN_ON_UNSAVED_CHANGE:
'general-settings:saved-views:warn-on-unsaved-change',
DASHBOARD_VIEWS_VISIBLE_IDS:
@@ -223,6 +224,11 @@ export const SETTINGS: UiSetting[] = [
type: 'string',
default: '',
},
{
key: SETTINGS_KEYS.WHATS_NEW_LAST_SEEN_VERSION,
type: 'string',
default: '',
},
{
key: SETTINGS_KEYS.SAVED_VIEWS_WARN_ON_UNSAVED_CHANGE,
type: 'boolean',
@@ -40,4 +40,21 @@ describe('RemoteVersionService', () => {
)
expect(req.request.method).toEqual('GET')
})
it('should call release notes endpoint without since', () => {
subscription = service.getReleaseNotes().subscribe()
const req = httpTestingController.expectOne(
`${environment.apiBaseUrl}release_notes/`
)
expect(req.request.method).toEqual('GET')
expect(req.request.params.has('since')).toBe(false)
})
it('should pass since to release notes endpoint', () => {
subscription = service.getReleaseNotes('3.4.2').subscribe()
const req = httpTestingController.expectOne(
`${environment.apiBaseUrl}release_notes/?since=3.4.2`
)
expect(req.request.method).toEqual('GET')
})
})
@@ -1,4 +1,4 @@
import { HttpClient } from '@angular/common/http'
import { HttpClient, HttpParams } from '@angular/common/http'
import { Injectable, inject } from '@angular/core'
import { Observable } from 'rxjs'
import { environment } from 'src/environments/environment'
@@ -8,6 +8,20 @@ export interface AppRemoteVersion {
update_available: boolean
}
export interface AppRelease {
version: string
name: string
body_html: string
html_url: string
published_at: string
}
export interface AppReleaseNotes {
version: string
releases: AppRelease[]
stars: number | null
}
@Injectable({
providedIn: 'root',
})
@@ -19,4 +33,15 @@ export class RemoteVersionService {
`${environment.apiBaseUrl}remote_version/`
)
}
public getReleaseNotes(since?: string): Observable<AppReleaseNotes> {
let params = new HttpParams()
if (since) {
params = params.set('since', since)
}
return this.http.get<AppReleaseNotes>(
`${environment.apiBaseUrl}release_notes/`,
{ params }
)
}
}
@@ -398,6 +398,60 @@ describe('SettingsService', () => {
expect(req.request.method).toEqual('POST')
})
it('seeds last seen version on first load', () => {
const settings = {
...ui_settings,
user: { ...ui_settings.user, is_superuser: true },
settings: {
...ui_settings.settings,
documentListSize: 50,
update_checking: { enabled: false, backend_setting: 'default' },
},
}
settings.settings['version'] = '3.5.1'
httpTestingController
.expectOne(`${environment.apiBaseUrl}ui_settings/`)
.flush(settings)
const req = httpTestingController.expectOne(
`${environment.apiBaseUrl}ui_settings/`
)
expect(req.request.method).toEqual('POST')
expect(req.request.body.settings.whats_new.last_seen_version).toEqual(
'3.5.1'
)
expect(settingsService.unseenReleasesSince()).toBeNull()
})
it('reports unseen releases and marks them seen', () => {
const settings = {
...ui_settings,
user: { ...ui_settings.user, is_superuser: true },
settings: {
...ui_settings.settings,
documentListSize: 50,
update_checking: { enabled: false, backend_setting: 'default' },
},
}
settings.settings['version'] = '3.5.1'
settings.settings['whats_new'] = { last_seen_version: '3.4.2' }
httpTestingController
.expectOne(`${environment.apiBaseUrl}ui_settings/`)
.flush(settings)
httpTestingController.expectNone(`${environment.apiBaseUrl}ui_settings/`)
expect(settingsService.unseenReleasesSince()).toEqual('3.4.2')
subscription = settingsService.markReleasesSeen().subscribe()
const req = httpTestingController.expectOne(
`${environment.apiBaseUrl}ui_settings/`
)
expect(req.request.body.settings.whats_new.last_seen_version).toEqual(
'3.5.1'
)
expect(settingsService.unseenReleasesSince()).toBeNull()
})
it('updates settings on complete tour', () => {
let req = httpTestingController.expectOne(
`${environment.apiBaseUrl}ui_settings/`
@@ -20,6 +20,7 @@ import {
hexToHsl,
} from 'src/app/utils/color'
import { DEFAULT_APP_TITLE, environment } from 'src/environments/environment'
import { compareVersions } from 'src/app/utils/version'
import { DEFAULT_DISPLAY_FIELDS, DisplayField } from '../data/document'
import { RemoteOCRModeConfig } from '../data/paperless-config'
import { SavedView } from '../data/saved-view'
@@ -327,6 +328,18 @@ export class SettingsService {
SETTINGS_KEYS.SIDEBAR_HIDDEN_ITEMS
)
/**
* The last version the user saw release notes for, if the running
* version is newer, or null.
*/
readonly unseenReleasesSince = computed<string | null>(() => {
this.settingsVersion()
const currentVersion = this.get(SETTINGS_KEYS.VERSION)
const lastSeen = this.get(SETTINGS_KEYS.WHATS_NEW_LAST_SEEN_VERSION)
if (!currentVersion || !lastSeen) return null
return compareVersions(currentVersion, lastSeen) > 0 ? lastSeen : null
})
readonly allDisplayFields = signal<Array<{ id: DisplayField; name: string }>>(
DEFAULT_DISPLAY_FIELDS
)
@@ -384,6 +397,7 @@ export class SettingsService {
uisettings.permissions,
this.currentUser()
)
this.maybeSeedLastSeenVersion()
this.initializeDisplayFields()
})
@@ -713,6 +727,34 @@ export class SettingsService {
return this.settingIsSet(SETTINGS_KEYS.UPDATE_CHECKING_ENABLED)
}
/**
* Record the baseline version for "what's new" tracking.
*/
private maybeSeedLastSeenVersion() {
const currentVersion = this.get(SETTINGS_KEYS.VERSION)
if (
!currentVersion ||
this.get(SETTINGS_KEYS.WHATS_NEW_LAST_SEEN_VERSION) ||
!this.permissionsService.currentUserCan(
PermissionAction.Change,
PermissionType.UISettings
)
)
return
this.set(SETTINGS_KEYS.WHATS_NEW_LAST_SEEN_VERSION, currentVersion)
this.storeSettings()
.pipe(first())
.subscribe({ error: () => {} })
}
public markReleasesSeen(): Observable<any> {
this.set(
SETTINGS_KEYS.WHATS_NEW_LAST_SEEN_VERSION,
this.get(SETTINGS_KEYS.VERSION)
)
return this.storeSettings()
}
/**
* Offering remote OCR as a choice only makes sense when an engine
* is configured but is not already handling every document.
+11
View File
@@ -0,0 +1,11 @@
import { compareVersions } from './version'
describe('compareVersions', () => {
it('should compare versions numerically', () => {
expect(compareVersions('3.5.1', '3.5.0')).toBeGreaterThan(0)
expect(compareVersions('3.10.0', '3.9.9')).toBeGreaterThan(0)
expect(compareVersions('3.4.2', '3.5.0')).toBeLessThan(0)
expect(compareVersions('3.5.0', '3.5.0')).toEqual(0)
expect(compareVersions('3.5', '3.5.0')).toEqual(0)
})
})
+13
View File
@@ -0,0 +1,13 @@
/**
* Compare two X.Y.Z version strings numerically.
* Returns a positive number if a > b, negative if a < b, 0 if equal.
*/
export function compareVersions(a: string, b: string): number {
const partsA = a.split('.').map((p) => parseInt(p, 10) || 0)
const partsB = b.split('.').map((p) => parseInt(p, 10) || 0)
for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0)
if (diff !== 0) return diff
}
return 0
}
+3
View File
@@ -13,6 +13,9 @@ $form-file-button-hover-bg: var(--pngx-bg-alt);
@include meta.load-css("print");
// re-created bootstrap styles
.mt-n1 {
margin-top: -0.25rem;
}
.mt-n2 {
margin-top: -0.5rem;
}
@@ -0,0 +1,200 @@
import pytest
from django.core.cache import cache
from pytest_httpx import HTTPXMock
from rest_framework import status
from rest_framework.test import APIClient
from paperless import version
REPO_URL = "https://api.github.com/repos/paperless-ngx/paperless-ngx"
RELEASES_URL = f"{REPO_URL}/releases?per_page=10"
def _release(tag: str, **kwargs) -> dict:
return {
"tag_name": tag,
"name": f"Paperless-ngx {tag}",
"body_html": f"<h2>paperless-ngx {tag}</h2>",
"html_url": f"https://github.com/paperless-ngx/paperless-ngx/releases/tag/{tag}",
"published_at": "2026-11-17T03:36:20Z",
"draft": False,
"prerelease": False,
**kwargs,
}
def _bump(minor: int = 0, patch: int = 0) -> str:
major, cur_minor, cur_patch = version.__version__
return f"{major}.{cur_minor + minor}.{cur_patch + patch}"
CURRENT = version.__full_version_str__
PREVIOUS = f"{version.__version__[0]}.{version.__version__[1] - 1}.0"
OLDER = f"{version.__version__[0]}.{version.__version__[1] - 2}.0"
class TestApiReleaseNotes:
ENDPOINT = "/api/release_notes/"
def setup_method(self) -> None:
cache.clear()
@pytest.fixture
def releases(self, httpx_mock: HTTPXMock) -> HTTPXMock:
httpx_mock.add_response(
url=RELEASES_URL,
match_headers={"Accept": "application/vnd.github.html+json"},
json=[
_release(f"v{_bump(patch=1)}"),
_release(f"v{_bump(minor=1)}-beta.1", prerelease=True),
_release(f"v{CURRENT}"),
_release(f"v{PREVIOUS}"),
_release(f"ngx-{OLDER}"),
],
)
return httpx_mock
@pytest.fixture
def stars(self, httpx_mock: HTTPXMock) -> HTTPXMock:
httpx_mock.add_response(url=REPO_URL, json={"stargazers_count": 1234})
return httpx_mock
@pytest.mark.usefixtures("stars")
def test_since_returns_newer_up_to_current(
self,
rest_api_client: APIClient,
releases: HTTPXMock,
) -> None:
"""
GIVEN:
- GitHub releases older, equal to, and newer than the running version
WHEN:
- Release notes are requested since an older version
THEN:
- Only releases after `since` up to the running version are returned,
newest first, excluding prereleases and the `since` release itself
"""
response = rest_api_client.get(self.ENDPOINT, {"since": OLDER})
assert response.status_code == status.HTTP_200_OK
assert response.data["version"] == CURRENT
assert [r["version"] for r in response.data["releases"]] == [
CURRENT,
PREVIOUS,
]
assert response.data["releases"][0]["html_url"].endswith(f"v{CURRENT}")
assert (
response.data["releases"][0]["body_html"]
== f"<h2>paperless-ngx v{CURRENT}</h2>"
)
@pytest.mark.usefixtures("stars")
def test_without_since_returns_current_only(
self,
rest_api_client: APIClient,
releases: HTTPXMock,
) -> None:
response = rest_api_client.get(self.ENDPOINT)
assert response.status_code == status.HTTP_200_OK
assert [r["version"] for r in response.data["releases"]] == [CURRENT]
@pytest.mark.usefixtures("stars")
def test_releases_are_cached(
self,
rest_api_client: APIClient,
releases: HTTPXMock,
) -> None:
rest_api_client.get(self.ENDPOINT, {"since": OLDER})
rest_api_client.get(self.ENDPOINT)
assert len(releases.get_requests(url=RELEASES_URL)) == 1
assert len(releases.get_requests(url=REPO_URL)) == 1
def test_invalid_since(
self,
rest_api_client: APIClient,
) -> None:
response = rest_api_client.get(self.ENDPOINT, {"since": "not-a-version"})
assert response.status_code == status.HTTP_400_BAD_REQUEST
@pytest.mark.parametrize(
"mock_kwargs",
[
pytest.param({"status_code": 503}, id="http-error"),
pytest.param(
{
"content": b'{ "blah":',
"headers": {"Content-Type": "application/json"},
},
id="bad-json",
),
],
)
def test_github_failure_returns_empty_and_is_not_cached(
self,
rest_api_client: APIClient,
httpx_mock: HTTPXMock,
mock_kwargs: dict,
) -> None:
httpx_mock.add_response(url=RELEASES_URL, **mock_kwargs)
httpx_mock.add_response(url=RELEASES_URL, json=[_release(f"v{CURRENT}")])
httpx_mock.add_response(
url=REPO_URL,
json={"stargazers_count": 1234},
is_reusable=True,
)
response = rest_api_client.get(self.ENDPOINT)
assert response.status_code == status.HTTP_200_OK
assert response.data["releases"] == []
response = rest_api_client.get(self.ENDPOINT)
assert [r["version"] for r in response.data["releases"]] == [CURRENT]
@pytest.mark.usefixtures("releases", "stars")
def test_stars_are_returned_and_cached(
self,
rest_api_client: APIClient,
httpx_mock: HTTPXMock,
) -> None:
"""
GIVEN:
- The GitHub repository reports a star count
WHEN:
- Release notes are requested twice
THEN:
- The star count is included and GitHub is only asked once
"""
response = rest_api_client.get(self.ENDPOINT)
assert response.data["stars"] == 1234
response = rest_api_client.get(self.ENDPOINT)
assert response.data["stars"] == 1234
assert len(httpx_mock.get_requests(url=REPO_URL)) == 1
@pytest.mark.usefixtures("releases")
def test_stars_failure_returns_none_and_is_not_cached(
self,
rest_api_client: APIClient,
httpx_mock: HTTPXMock,
) -> None:
"""
GIVEN:
- The GitHub repository request fails, then succeeds
WHEN:
- Release notes are requested twice
THEN:
- Stars are null at first, then fetched again rather than cached
"""
httpx_mock.add_response(url=REPO_URL, status_code=503)
httpx_mock.add_response(url=REPO_URL, json={"stargazers_count": 1234})
response = rest_api_client.get(self.ENDPOINT)
assert response.status_code == status.HTTP_200_OK
assert response.data["stars"] is None
assert len(response.data["releases"]) == 1
response = rest_api_client.get(self.ENDPOINT)
assert response.data["stars"] == 1234
+94 -6
View File
@@ -1,3 +1,5 @@
from unittest import mock
from django.core.cache import cache
from pytest_httpx import HTTPXMock
from rest_framework import status
@@ -5,6 +7,17 @@ from rest_framework.test import APIClient
from paperless import version
REPO_URL = "https://api.github.com/repos/paperless-ngx/paperless-ngx"
RELEASES_URL = f"{REPO_URL}/releases?per_page=10"
def _release(tag: str, **kwargs) -> dict:
return {
"tag_name": tag,
"html_url": f"https://github.com/paperless-ngx/paperless-ngx/releases/tag/{tag}",
**kwargs,
}
class TestApiRemoteVersion:
ENDPOINT = "/api/remote_version/"
@@ -18,8 +31,8 @@ class TestApiRemoteVersion:
httpx_mock: HTTPXMock,
) -> None:
httpx_mock.add_response(
url="https://api.github.com/repos/paperless-ngx/paperless-ngx/releases/latest",
json={"tag_name": "ngx-1.6.0"},
url=RELEASES_URL,
json=[_release("ngx-1.6.0")],
)
response = rest_api_client.get(self.ENDPOINT)
@@ -37,8 +50,8 @@ class TestApiRemoteVersion:
httpx_mock: HTTPXMock,
) -> None:
httpx_mock.add_response(
url="https://api.github.com/repos/paperless-ngx/paperless-ngx/releases/latest",
json={"tag_name": version.__full_version_str__},
url=RELEASES_URL,
json=[_release(version.__full_version_str__)],
)
response = rest_api_client.get(self.ENDPOINT)
@@ -63,8 +76,8 @@ class TestApiRemoteVersion:
new_version_str = ".".join(map(str, new_version))
httpx_mock.add_response(
url="https://api.github.com/repos/paperless-ngx/paperless-ngx/releases/latest",
json={"tag_name": new_version_str},
url=RELEASES_URL,
json=[_release(new_version_str)],
)
response = rest_api_client.get(self.ENDPOINT)
@@ -110,3 +123,78 @@ class TestApiRemoteVersion:
assert "update_available" in response.data
assert not response.data["update_available"]
def test_remote_version_uses_highest_published_release(
self,
rest_api_client: APIClient,
httpx_mock: HTTPXMock,
) -> None:
"""
GIVEN:
- A backport release listed before a newer release, and a newer prerelease
WHEN:
- The remote version is requested
THEN:
- The highest non-prerelease version is reported
"""
major, minor, patch = version.__version__
newer = f"{major}.{minor}.{patch + 1}"
httpx_mock.add_response(
url=RELEASES_URL,
json=[
_release(f"v{major + 1}.0.0-beta.1", prerelease=True),
_release(f"v{major - 1}.9.9"),
_release(f"v{newer}"),
],
)
response = rest_api_client.get(self.ENDPOINT)
assert response.data["version"] == newer
assert response.data["update_available"]
def test_remote_version_and_release_notes_share_request(
self,
rest_api_client: APIClient,
httpx_mock: HTTPXMock,
) -> None:
httpx_mock.add_response(
url=RELEASES_URL,
json=[_release(f"v{version.__full_version_str__}")],
)
httpx_mock.add_response(url=REPO_URL, json={"stargazers_count": 1234})
rest_api_client.get(self.ENDPOINT)
response = rest_api_client.get("/api/release_notes/")
assert len(response.data["releases"]) == 1
assert len(httpx_mock.get_requests(url=RELEASES_URL)) == 1
def test_new_running_version_refetches_releases(
self,
rest_api_client: APIClient,
httpx_mock: HTTPXMock,
) -> None:
"""
GIVEN:
- GitHub releases cached for the running version
WHEN:
- The running version changes (i.e. paperless was upgraded)
THEN:
- The cached releases are not reused and GitHub is queried again
"""
major, minor, patch = version.__version__
upgraded = f"{major}.{minor}.{patch + 1}"
httpx_mock.add_response(
url=RELEASES_URL,
json=[_release(f"v{version.__full_version_str__}")],
)
httpx_mock.add_response(url=RELEASES_URL, json=[_release(f"v{upgraded}")])
httpx_mock.add_response(url=REPO_URL, json={"stargazers_count": 1234})
rest_api_client.get(self.ENDPOINT)
with mock.patch.object(version, "__full_version_str__", upgraded):
response = rest_api_client.get("/api/release_notes/")
assert len(httpx_mock.get_requests(url=RELEASES_URL)) == 2
assert [r["version"] for r in response.data["releases"]] == [upgraded]
+127 -23
View File
@@ -4314,6 +4314,77 @@ class UiSettingsView(GenericAPIView[Any]):
)
GITHUB_CACHE_KEY = "github_data:%s"
def get_github_releases(
current_version: packaging_version.Version,
) -> list[dict[str, Any]] | None:
"""
Fetch recent pngx releases from GitHub, newest first.
"""
releases = cache.get(GITHUB_CACHE_KEY % current_version)
if releases is not None:
return releases
try:
resp = httpx.get(
"https://api.github.com/repos/paperless-ngx/paperless-ngx/releases",
params={"per_page": 10},
# GitHub renders release bodies as HTML
headers={"Accept": "application/vnd.github.html+json"},
)
resp.raise_for_status()
releases = []
for release in resp.json():
if release.get("draft") or release.get("prerelease"):
continue
try:
# Some early tags used ngx-x.y.z
release_version = packaging_version.parse(
release["tag_name"].removeprefix("ngx-"),
)
except packaging_version.InvalidVersion:
continue
releases.append(
{
"version": str(release_version),
"name": release.get("name") or release["tag_name"],
"body_html": release.get("body_html") or "",
"html_url": release["html_url"],
"published_at": release.get("published_at"),
},
)
except (ValueError, KeyError, TypeError) as e:
logger.debug(f"An error occurred parsing GitHub releases json: {e}")
return None
except httpx.HTTPError as e:
logger.debug(f"An error occurred fetching GitHub releases: {e}")
return None
cache.set(GITHUB_CACHE_KEY % current_version, releases, 60 * 60)
return releases
def get_github_stars() -> int | None:
"""
Fetch the number of stars for the Paperless-NGX repository from GitHub.
"""
count = cache.get(GITHUB_CACHE_KEY % "stars")
if count is not None:
return count
try:
resp = httpx.get(
"https://api.github.com/repos/paperless-ngx/paperless-ngx",
headers={"Accept": "application/vnd.github+json"},
)
resp.raise_for_status()
count = resp.json()["stargazers_count"]
except Exception as e:
logger.debug(f"An error occurred fetching GitHub stars: {e}")
return None
cache.set(GITHUB_CACHE_KEY % "stars", count, 60 * 60)
return count
@extend_schema_view(
get=extend_schema(
description="Get the current version of the Paperless-NGX server",
@@ -4323,31 +4394,16 @@ class UiSettingsView(GenericAPIView[Any]):
),
)
class RemoteVersionView(GenericAPIView[Any]):
cache_key = "remote_version_view_latest_release"
def get(self, request, format=None):
current_version = packaging_version.parse(version.__full_version_str__)
remote_version = cache.get(self.cache_key)
if remote_version is None:
try:
resp = httpx.get(
"https://api.github.com/repos/paperless-ngx/paperless-ngx/releases/latest",
headers={"Accept": "application/json"},
)
resp.raise_for_status()
data = resp.json()
remote_version = data["tag_name"]
# Some early tags used ngx-x.y.z
remote_version = remote_version.removeprefix("ngx-")
except ValueError as e:
logger.debug(f"An error occurred parsing remote version json: {e}")
except httpx.HTTPError as e:
logger.debug(f"An error occurred checking for available updates: {e}")
if remote_version:
cache.set(self.cache_key, remote_version, 60 * 15)
else:
remote_version = "0.0.0"
releases = get_github_releases(current_version)
remote_version = (
max(releases, key=lambda r: packaging_version.parse(r["version"]))[
"version"
]
if releases
else "0.0.0"
)
is_greater_than_current = (
packaging_version.parse(remote_version) > current_version
@@ -4361,6 +4417,54 @@ class RemoteVersionView(GenericAPIView[Any]):
)
@extend_schema_view(
get=extend_schema(
description=(
"Get release notes from GitHub for releases newer than `since`, "
"up to and including the running version. Without `since`, only "
"the running version's notes are returned."
),
parameters=[
OpenApiParameter(
name="since",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
required=False,
),
],
responses={
(200, "application/json"): OpenApiTypes.OBJECT,
},
),
)
class ReleaseNotesView(GenericAPIView[Any]):
def get(self, request, format=None):
current_version = packaging_version.parse(version.__full_version_str__)
since_param = request.query_params.get("since")
since = None
if since_param:
try:
since = packaging_version.parse(since_param)
except packaging_version.InvalidVersion:
return HttpResponseBadRequest("Invalid since version")
releases = get_github_releases(current_version) or []
def in_range(release_version: str) -> bool:
v = packaging_version.parse(release_version)
if since is None:
return v == current_version
return since < v <= current_version
return Response(
{
"version": version.__full_version_str__,
"releases": [r for r in releases if in_range(r["version"])],
"stars": get_github_stars(),
},
)
class _TasksViewSetSchema(AutoSchema):
_UNPAGINATED_ACTIONS = frozenset({"summary", "active", "status_counts"})
+2 -2
View File
@@ -3,7 +3,7 @@ msgstr ""
"Project-Id-Version: paperless-ngx\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-11-17 20:48+0000\n"
"PO-Revision-Date: 2026-11-18 04:15\n"
"PO-Revision-Date: 2026-11-17 20:49\n"
"Last-Translator: \n"
"Language-Team: Italian\n"
"Language: it_IT\n"
@@ -1002,7 +1002,7 @@ msgstr ""
#: documents/models.py:1011
msgid "Markdown"
msgstr "Annotare"
msgstr ""
#: documents/models.py:1016
msgid "Note for the document"
+6
View File
@@ -31,6 +31,7 @@ from documents.views import LogViewSet
from documents.views import MergeDocumentsAsVersionsView
from documents.views import MergeDocumentsView
from documents.views import PostDocumentView
from documents.views import ReleaseNotesView
from documents.views import RemoteVersionView
from documents.views import RemovePasswordDocumentsView
from documents.views import ReprocessDocumentsView
@@ -219,6 +220,11 @@ urlpatterns = [
RemoteVersionView.as_view(),
name="remoteversion",
),
re_path(
"^release_notes/",
ReleaseNotesView.as_view(),
name="release_notes",
),
re_path(
"^ui_settings/",
UiSettingsView.as_view(),