Versiones semánticas automáticas en proyectos Gradle
Cómo usar las especificaciones de control de versiones semánticas en sus proyectos Gradle de Android y no Android.
este Versionado semántico Una especificación consta de varias convenciones para asignar e incrementar los números de versión de su software. Puedes leer todas las especificaciones aquí.
Básicamente, la idea es la siguiente:
Los números de versión normales deben tener el formato XYZ, donde X, Y y Z son números enteros no negativos y no deben contener ceros a la izquierda. X es la versión principal, Y es la versión secundaria y Z es la versión de parche. Cada elemento debe incrementarse numéricamente. Por ejemplo: 1.9.0 -> 1.10.0 -> 1.11.0.
Dado el número de versión PRINCIPAL.MENOR.PARCHE, incremente:
- versión principal cuando se realizaron cambios de API incompatibles,
- Versiones secundarias cuando se agregan funciones de manera compatible con versiones anteriores, y
- Versión de parche para correcciones de errores de compatibilidad con versiones anteriores.
prelanzamiento
Un concepto importante de la definición de versionado semántico es que prelanzamiento Versión.Las versiones preliminares están disponibles agregando un Clasificador de versiones comienza con un -. P.ej 3.1.0-beta, 1.2.0-rc, 4.1.3-preview, 2.3.0-alpha, 1.3.2-SNAPSHOT.
Puede usar estos clasificadores de versiones para identificar rápidamente el tipo de versión de un proyecto y evitar confusiones entre versiones preliminares y versiones de lanzamiento.Por ejemplo, en proyectos Gradle es común usar -SNAPSHOT Este clasificador se elimina durante la fase de desarrollo y cuando se lanza el proyecto.
Proyectos sin una API pública
El primer elemento de la especificación de versiones semánticas dice:
El software que utiliza versiones semánticas debe declarar una API pública.
Para algunos tipos de proyectos, donde no tiene ningún tipo de API disponible para otros clientes, entonces la versión PRINCIPAL podría no tener sentido. La mayoría de las aplicaciones de Android o cliente son un ejemplo. En su mayor parte, no exponen ningún tipo de API.En estos casos, no se puede utilizar pura Versionado semántico Especificación. Debe definir cuándo se debe aumentar la versión PRINCIPAL.
Una opción podría ser agregar PRINCIPAL cuando la aplicación tiene nuevas funciones, rediseños u objetivos importantes. Otra forma es incrementar el MAYOR después de alcanzar la versión MENOR, por ejemplo, el número 99.Por ejemplo, puede tener una versión 1.0.0, 1.1.0… 1.99.0 y luego 2.0.0Esta es solo una convención para decidir cuándo aumentar MAYOR. Puede utilizar cualquier convención siempre que esté claramente definida y entendida por todos los interesados de su proyecto.
Con el complemento de Gradle Versionado semántico, puede aplicar automáticamente las especificaciones de Versionado semántico a sus proyectos de Gradle.
Aplicar complemento en la raíz build.gradle[.kts]reemplace XYZ con la última versión:
buildscript {
repositories {
mavenCentral() // or gradlePluginPortal()
}
dependencies {
classpath("com.dipien:semantic-version-gradle-plugin:X.Y.Z")
}
}apply plugin: "com.dipien.semantic-version"
Defina la versión de su proyecto en su directorio raíz build.gradle[.kts] Usando la especificación de versiones semánticas pero sin ningún clasificador:
version = "1.0.0"El complemento asignará la versión del proyecto raíz a todos sus subproyectos.
Puedes apoyar esta publicación haciéndote miembro de Medium y obteniendo acceso ilimitado a cada historia. Los autores recibirán una parte de su cuota de membresía.Simplemente compre una membresía mediana aquí
este printVersion La tarea imprime la versión del proyecto en la consola.
./gradlew printVersion
OUTPUT: Version: 1.0.0-SNAPSHOTpor defecto, SNAPSHOT El clasificador está habilitado.puedes usarlo -Psnapshot=false En cualquier momento que desee utilizar la versión estable de los parámetros. Por ejemplo, al publicar artefactos, generar publicar paquetes de aplicaciones de Android, etc.
./gradlew printVersion -Psnapshot=false
OUTPUT: Version: 1.0.0puedes usarlo alpha o beta Clasificador:
./gradlew printVersion -Palpha=true
OUTPUT: Version: 1.0.0-ALPHA./gradlew printVersion -Pbeta=true
OUTPUT: 1.0.0-BETA
También puedes usar versionClassifier alcance:
./gradlew printVersion -PversionClassifier=canary
OUTPUT: 1.0.0-canaryeste incrementVersion La tarea incrementa la versión del proyecto en el directorio raíz build.gradle[.kts] documento.este versionIncrementType Las opciones definen el tipo de incremento: MAJOR, MINOR o PATCH
// Increments the major from 1.0.0 to 2.0.0
./gradlew incrementVersion --versionIncrementType=MAJOR// Increments the minor from 1.0.0 to 1.1.0
./gradlew incrementVersion --versionIncrementType=MINOR// Increments the patch from 1.0.0 to 1.0.1
./gradlew incrementVersion --versionIncrementType=PATCH
Si también desea confirmar y enviar cambios de versión, simplemente agregue versionIncrementBranch Opciones para la rama HEAD.
./gradlew incrementVersion --versionIncrementType=MAJOR --versionIncrementBranch=master -PgitUserName=userName [email protected]Puede crear una acción de GitHub para desencadenar fácilmente incrementos de versión. Sólo tienes que seguir estos tres sencillos pasos.
- Si trabaja para una empresa o sus repositorios están en una organización de Github, se recomienda utilizar una cuenta de Github específica de CI en lugar de su cuenta personal. Las acciones de GitHub usarán esta cuenta para impulsar los incrementos de versión. Simplemente cree una nueva cuenta de Github y utilícela en todos sus entornos de CI.
2. Defina estos 2 secretos de GitHub relacionados con el usuario de CI creado en el paso anterior:
GIT_USER_EMAIL-> buzón de usuario de gitGIT_USER_NAME-> nombre de usuario git
Puede configurar estos secretos a nivel de organización (organization settings -> secrets) o a nivel de repositorio (repository settings -> secrets).
3. Empuje el siguiente código fuente para .github/workflows/increment_version.yml documento.
Todas las propiedades de configuración se pueden agregar de cualquiera de las siguientes maneras:
- usar
semanticVersionextensión en la raízbuild.gradle[.kts]
semanticVersion {
gitUserEmail = "[email protected]"
}- Como argumentos de línea de comando:
./gradlew ... -PgitUserEmail="[email protected]"- como un atributo
gradle.propertiesdocumento:
gitUserEmail = "[email protected]"- como un atributo adicional en la raíz
build.gradleobuild.gradle.kts:
ext.gitUserEmail = "[email protected]"- como una propiedad del entorno del sistema
versión más alta
este maximumVersion El parámetro indica el valor máximo permitido MAJOR, MINOR o PATCH. El valor predeterminado es 99por lo que por defecto 99.99.99 es la versión más grande compatible.
instantánea
este snapshot El parámetro indica si la versión debe tener -SNAPSHOT Clasificador o no. De forma predeterminada, todas las versiones se consideran instantáneas, por lo que todas las compilaciones locales no interferirán con las compilaciones de lanzamiento.
beta
este beta El parámetro indica si la versión debe tener -BETA Clasificador o no.
Alfa
este alpha El parámetro indica si la versión debe tener -ALPHA Clasificador o no.
Clasificador de versiones
este versionClassifier El parámetro representa el clasificador para adjuntar a la versión. Puede utilizar esta propiedad para definir un clasificador de versión personalizado.
El complemento tiene algunas características especiales para proyectos de Android.solo necesitas aplicar com.dipien.android.semantic-version complemento en su lugar com.dipien.semantic-version.
Simplemente agregue esta configuración a su directorio raíz build.gradle[.kts]archivo, reemplace XYZ con la última versión
buildscript {
repositories {
mavenCentral() // or gradlePluginPortal()
}
dependencies {
classpath("com.dipien:semantic-version-android-gradle-plugin:X.Y.Z")
}
}apply plugin: "com.dipien.android.semantic-version"
Código de versión y nombre de versión
En Android, debe definir dos campos de versión para su aplicación:
- código de versión (
android:versionCodeEn tuAndroidManifest.xml). El código de versión es un valor entero incremental que representa la versión del código de la aplicación. El código de versión máximo permitido por Google Play es 2100000000. - nombre de la versión (
android:versionNameEn tuAndroidManifest.xml). El nombre de la versión es un valor de cadena que representa el nombre de la versión «amigable» que se muestra al usuario.
Puedes obtener mas detalles aqui.
Es mejor tener una relación directa entre las dos versiones para evitar confusiones durante el desarrollo y el lanzamiento. Como mínimo, debería poder deducir el nombre de la versión del código de la versión.
Como se indica aquí, la documentación oficial recomienda usar Esquema de código de versión Asocia códigos y nombres de versión, y también admite múltiples APK. El complemento utiliza este esquema con algunos cambios para admitir el control de versiones semántico.
Esquema de control de versión simple
Con la introducción del formato App Bundle, en la mayoría de los casos no necesitará compatibilidad con varios APK.
Por lo tanto, puede usar un código de versión de 6 bits que represente la versión semántica: los dos primeros son la versión MAYOR, los dos siguientes son MENOR y los dos últimos son la versión PATCH.
Como puede ver, puede actualizar desde la versión 0.0.1 a la 99.99.99. Entonces, tiene más de 192 años de espacio de versión, con lanzamientos semanales, ¡sin parches! ! !
Este esquema de control de versiones simple es el predeterminado para los complementos.
Para proyectos de Android, printVersion La tarea imprime la versión del proyecto, el nombre de la versión de la aplicación de Android y el código de la versión.
./gradlew printVersionOUTPUT:
Version: 1.0.0-SNAPSHOT
Version code: 10000
Version name: 1.0.0-SNAPSHOT
Dado el valor predeterminado maximumVersion El parámetro es 99 y el número de versión máximo generado es 999999.Tenga en cuenta que aumentar este valor afectará el número de versión generado, limitado a 2100000000
Si necesita comenzar a utilizar la compatibilidad con múltiples APK, puede cambiar a un esquema de versiones más avanzado que sea totalmente compatible con el esquema de versiones simple anterior. Código de versión de 9 bits: indica que el número entero que admite la configuración está en el bit alto y la versión está en el bit bajo.
- Los primeros dos números representan el nivel mínimo de API de tu APK.
- El siguiente número es para el tamaño de la pantalla o el formato de textura GL (asigne cero si no necesita usarlo).
- Luego hay dos dígitos para la versión principal, dos dígitos para la versión secundaria y los dos últimos dígitos para la versión del parche.
Por ejemplo, cuando el nombre de la versión de la aplicación es 3.1.0, el código de versión para un APK de nivel 4 de API mínimo sería algo así como 040030100Los dos primeros bits están reservados para el nivel de API más bajo (4 en este ejemplo), el tercero es para el tamaño de la pantalla o el formato de textura GL (no se usa en este ejemplo, por lo que se le asigna 0) y los últimos seis bits son el nombre de la versión. de la aplicación (3.1.0).
En el complemento, cuandominSdkVersionAsVersionCodePrefix el parámetro se establece en true, la versión mínima de SDK como prefijo del código de versión.Entonces puedes usar versionCodeExtraBit Un parámetro utilizado para definir el tercer número (por ejemplo, para el tamaño de la pantalla o el formato de textura GL).Por ejemplo, la siguiente configuración generará el código de versión 215010203:
/build.gradle
version = "1.2.3"apply plugin: "com.dipien.android.semantic-version"semanticVersion {
minSdkVersionAsVersionCodePrefix = true
versionCodeExtraBit = 5
}
/app/build.gradle
apply plugin: 'com.android.application'android {
...defaultConfig {
minSdkVersion 21
...
}
}
si configuras minSdkVersionAsVersionCodePrefix el parámetro es falso, entonces puede definir un parámetro personalizado versionCodePrefixPor ejemplo, la siguiente configuración generará código de versión 35010203:
/build.gradle
version = "1.2.3"apply plugin: "com.dipien.android.semantic-version"semanticVersion {
minSdkVersionAsVersionCodePrefix = false
versionCodeExtraBit = 5
versionCodePrefix = 3
}
Si usa el programa de prueba Google Play Alpha/Beta, tenga en cuenta que el nombre de la versión de carga comienza con alpha o betaLa razón es que cuando implementa un paquete de aplicaciones en producción, no puede cambiar el nombre de la versión, por lo que sus usuarios creerán que tienen una versión inestable instalada.
