Merge pull request #66021 from nextcloud/backport/65922/stable34

[stable34] fix(since): Ensure provided since version is from the current branch

Author: kesselb

build/psalm/OcpSinceChecker.php

@@ -140,6 +140,9 @@ private static function checkClassComment(ClassLike $stmt, FileSource $statement
 				)
 			);
 		}
+		foreach ($parsedDocblock->tags['since'] ?? [] as $since) {
+			self::checkSinceIsReleasable(trim($since), $statementsSource, $stmt);
+		}
 
 		if (isset($parsedDocblock->tags['depreacted'])) {
 			IssueBuffer::maybeAdd(
@@ -184,6 +187,9 @@ private static function checkStatementComment(Stmt $stmt, FileSource $statements
 				)
 			);
 		}
+		foreach ($parsedDocblock->tags['since'] ?? [] as $since) {
+			self::checkSinceIsReleasable(trim($since), $statementsSource, $stmt);
+		}
 
 		if (isset($parsedDocblock->tags['depreacted'])) {
 			IssueBuffer::maybeAdd(
@@ -213,9 +219,46 @@ private static function checkAttributeHasValidSinceVersion(\PhpParser\Node\Attri
 								new CodeLocation($statementsSource, $stmt)
 							)
 						);
+					} else {
+						self::checkSinceIsReleasable($arg->value->value, $statementsSource, $stmt);
 					}
 				}
 			}
 		}
 	}
+
+	/**
+	 * A since version must not be newer than the next patch release of the
+	 * current branch, so backports with an unadjusted since fail
+	 */
+	private static function checkSinceIsReleasable(string $since, FileSource $statementsSource, \PhpParser\Node $stmt): void {
+		// Backports may list multiple versions: "33.0.1, 32.0.7"
+		if (!preg_match('/^\d+(\.\d+)*(\s*,\s*\d+(\.\d+)*)*/', $since, $list)) {
+			return;
+		}
+
+		$maxVersion = self::getMaxSinceVersion();
+		foreach (preg_split('/\s*,\s*/', $list[0]) as $version) {
+			if (version_compare($version, $maxVersion, '<=')) {
+				return;
+			}
+		}
+
+		IssueBuffer::maybeAdd(
+			new InvalidDocblock(
+				'Since version ' . $list[0] . ' is newer than the next release ' . $maxVersion . ' of this branch, please adjust it to the version the change is released in.',
+				new CodeLocation($statementsSource, $stmt)
+			)
+		);
+	}
+
+	private static function getMaxSinceVersion(): string {
+		static $maxVersion = null;
+		if ($maxVersion === null) {
+			require __DIR__ . '/../../version.php';
+			/** @var array{0: int, 1: int, 2: int, 3: int} $OC_Version */
+			$maxVersion = $OC_Version[0] . '.' . $OC_Version[1] . '.' . ($OC_Version[2] + 1);
+		}
+		return $maxVersion;
+	}
 }

lib/public/Authentication/IProvideUserSecretBackend.php

@@ -27,7 +27,7 @@ interface IProvideUserSecretBackend {
 	 *                       secret but is unable to do so.
 	 *
 	 * @since 23.0.0
-	 * @since 35.0.0 The returns value is now optional.
+	 * @since 34.0.2 The returns value is now optional.
 	 */
 	public function getCurrentUserSecret(): ?string;
 }

lib/public/Calendar/CalendarImportOptions.php

@@ -158,7 +158,7 @@ public function setValidate(int $value): void {
 	/**
 	 * Gets whether to include object counts as the first yielded value
 	 *
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function getCounts(): bool {
 		return $this->counts;
@@ -167,7 +167,7 @@ public function getCounts(): bool {
 	/**
 	 * Sets whether to include object counts as the first yielded value
 	 *
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function setCounts(bool $counts): void {
 		$this->counts = $counts;

lib/public/Calendar/Events/CalendarObjectUpdatedEvent.php

@@ -36,7 +36,7 @@ public function __construct(
 	 * Returns the object data as it was before the update.
 	 *
 	 * @return array
-	 * @since 35.0.0
+	 * @since 34.0.0
 	 */
 	public function getOldObjectData(): array {
 		return $this->oldObjectData;

lib/public/Calendar/Room/IRoomMetadata.php

@@ -43,7 +43,7 @@ interface IRoomMetadata {
 	 * building from BUILDING_ADDRESS, which only works for backends that
 	 * happen to put the building name first.
 	 *
-	 * @since 35.0.0
+	 * @since 34.0.4
 	 */
 	public const BUILDING_NAME = '{http://nextcloud.com/ns}room-building-name';
 

lib/public/Contacts/ContactsImportOptions.php

@@ -13,45 +13,45 @@
 /**
  * Contacts Import Options
  *
- * @since 35.0.0
+ * @since 34.0.5
  */
 final class ContactsImportOptions {
 
 	/**
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public const FORMATS = ['vcf', 'jcf', 'xcf'];
 
 	/**
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public const VALIDATE_NONE = 0;
 	/**
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public const VALIDATE_SKIP = 1;
 	/**
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public const VALIDATE_FAIL = 2;
 	/**
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public const VALIDATE_OPTIONS = [
 		self::VALIDATE_NONE,
 		self::VALIDATE_SKIP,
 		self::VALIDATE_FAIL,
 	];
 	/**
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public const ERROR_CONTINUE = 0;
 	/**
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public const ERROR_FAIL = 1;
 	/**
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public const ERROR_OPTIONS = [
 		self::ERROR_CONTINUE,
@@ -69,7 +69,7 @@ final class ContactsImportOptions {
 	 * Gets the import format
 	 *
 	 * @return 'vcf'|'jcf'|'xcf' (defaults to vcf)
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function getFormat(): string {
 		return $this->format;
@@ -79,7 +79,7 @@ public function getFormat(): string {
 	 * Sets the import format
 	 *
 	 * @param 'vcf'|'jcf'|'xcf' $value
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function setFormat(string $value): void {
 		if (!in_array($value, self::FORMATS, true)) {
@@ -91,7 +91,7 @@ public function setFormat(string $value): void {
 	/**
 	 * Gets whether to supersede existing objects
 	 *
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function getSupersede(): bool {
 		return $this->supersede;
@@ -100,7 +100,7 @@ public function getSupersede(): bool {
 	/**
 	 * Sets whether to supersede existing objects
 	 *
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function setSupersede(bool $supersede): void {
 		$this->supersede = $supersede;
@@ -110,7 +110,7 @@ public function setSupersede(bool $supersede): void {
 	 * Gets how to handle object errors
 	 *
 	 * @return int 0 - continue, 1 - fail
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function getErrors(): int {
 		return $this->errors;
@@ -122,7 +122,7 @@ public function getErrors(): int {
 	 * @param int $value 0 - continue, 1 - fail
 	 *
 	 * @template $value of self::ERROR_*
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function setErrors(int $value): void {
 		if (!in_array($value, self::ERROR_OPTIONS, true)) {
@@ -135,7 +135,7 @@ public function setErrors(int $value): void {
 	 * Gets how to handle object validation
 	 *
 	 * @return int 0 - no validation, 1 - validate and skip on issue, 2 - validate and fail on issue
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function getValidate(): int {
 		return $this->validate;
@@ -147,7 +147,7 @@ public function getValidate(): int {
 	 * @param int $value 0 - no validation, 1 - validate and skip on issue, 2 - validate and fail on issue
 	 *
 	 * @template $value of self::VALIDATE_*
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function setValidate(int $value): void {
 		if (!in_array($value, self::VALIDATE_OPTIONS, true)) {
@@ -159,7 +159,7 @@ public function setValidate(int $value): void {
 	/**
 	 * Gets whether to include object counts as the first yielded value
 	 *
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function getCounts(): bool {
 		return $this->counts;
@@ -168,7 +168,7 @@ public function getCounts(): bool {
 	/**
 	 * Sets whether to include object counts as the first yielded value
 	 *
-	 * @since 35.0.0
+	 * @since 34.0.5
 	 */
 	public function setCounts(bool $counts): void {
 		$this->counts = $counts;

lib/public/DB/QueryBuilder/IFunctionBuilder.php

@@ -68,7 +68,7 @@ public function substring($input, $start, $length = null): IQueryFunction;
 	 * @param string|ILiteral|IParameter|IQueryFunction $pattern The pattern to match and return
 	 *
 	 * @return IQueryFunction
-	 * @since 36.0.0
+	 * @since 34.0.5
 	 */
 	public function regexSubstring($input, $pattern): IQueryFunction;
 

lib/public/Defaults.php

@@ -177,7 +177,7 @@ public function getLogo(bool $useSvg = true): string {
 	 * Raw logo image data (raster) for embedding directly into emails
 	 *
 	 * @return array{content: string, mimeType: string}|null null when unavailable
-	 * @since 35.0.0
+	 * @since 34.0.4
 	 */
 	public function getLogoImage(): ?array {
 		return $this->defaults->getLogoImage();

lib/public/FilesMetadata/IFilesMetadataManager.php

@@ -76,7 +76,7 @@ public function getMetadata(int $fileId, bool $generate = false): IFilesMetadata
 	 *
 	 * @return IFilesMetadata
 	 * @throws FilesMetadataNotFoundException if not found
-	 * @since 36.0.0
+	 * @since 34.0.6
 	 */
 	public function getMetadataForNode(Node $node, bool $generate = false): IFilesMetadata;
 

lib/public/FilesMetadata/Model/IFilesMetadata.php

@@ -49,7 +49,7 @@ public function getFileId(): int;
 	 * returns the storage id linked to this metadata
 	 *
 	 * @return int
-	 * @since 36.0.0
+	 * @since 34.0.6
 	 */
 	public function getStorageId(): int;