| name | project-conventions |
| description | Nextcloud Notes house conventions for any file you add, rename, or edit — SPDX header form, the 300-line and one-top-level-type-per-file limits, magic numbers, string/color/dimen resources, Java-interop annotations, and the verification commands that actually exist in this repository. Use when creating or renaming a file, and before reporting any change as done. |
Project Conventions (Nextcloud Notes)
Apply these to every file you write so the change passes review.
SPDX Header (every new/renamed file)
The IDE keeps the old license block. Replace it with the current template. The year is the
year the Kotlin file is created. New contributions are AGPL-3.0-or-later; keep
OR GPL-2.0-only only if the original file carried it.
If the developer wants personal attribution, the form
SPDX-FileCopyrightText: <YEAR> <Name> <email> is also used — match what the developer
asks for; default to the "Nextcloud GmbH and Nextcloud contributors" line.
Structural Rules
- ≤300 lines per file, and a file already at or above 300 lines must not grow. If
decomposition pushes past it, split responsibilities into separate files/collaborators and
tell the developer. Do not reach for
@Suppress("LargeClass", "TooManyFunctions") — those
are detekt rule names and this repository has no detekt, so the annotation suppresses
nothing and merely hides the problem from the reader.
- ≤120 columns per line.
- One top-level type per file. Extract models, states, sealed classes, and listener
interfaces into their own files rather than nesting many types in one.
- Exactly one trailing newline at end of file.
No Magic Numbers / Hardcoded Resources
- Extract literals into named
const val in a companion object
(MIN_SHOW_ALL_VISIBLE_ITEM_COUNT = 3, INTERNAL_LINK_PATH_PRETTY = "/f/").
- Strings, colors, dimens come from resources (
R.string.*, R.dimen.*), never inline.
- Only
app/src/main/res/values/strings.xml may be edited for strings; never touch
values-* translation folders.
Comments & Naming
- No decorative divider comments (
// ==== ====, // ---- Title ----). // region /
// endregion for IDE folding is allowed and should match the file's existing style.
- Prefer self-explanatory names over per-function KDoc. Preserve genuinely informative
Javadoc as KDoc (invariant 4); drop noise.
- Do not use multiple boolean flags to model state — use an
enum/sealed class.
Modern Java Interop
When the file still has Java callers, keep the Java-facing API clean:
@JvmStatic for factory/companion functions, @JvmField for exposed constants,
@JvmOverloads for defaulted params, @Throws for checked exceptions.
Git & Commits (developer-driven)
- Preserve history: the rename
git mv Foo.java Foo.kt should be a separate commit
from the content change so git blame follows through.
- Conventional Commits (
refactor(sharing): convert FileDetailSharingFragment to Kotlin).
- Every AI-assisted commit needs an
Assisted-by: <agent>:<model> trailer.
- Only the human contributor adds
Signed-off-by (DCO). You must never add it, and never
open PRs/issues autonomously (AI policy).
Quality Gate
These are the tasks this project actually has. gplay is not a flavor here — the flavors
are fdroid, play, dev, and qa.
./gradlew lintFdroidDebug
./gradlew testFdroidDebugUnitTest
./gradlew createFdroidDebugUnitTestCoverageReport
./gradlew check
Fix every finding in the files you changed before declaring done. Style rules that no task
enforces — line length, trailing newline, import order — are on you to check by reading the
diff.
