commit-convention-guide/index.html at main · BorchSolutions/commit-convention-guide · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
<!DOCTYPE html>
<html lang="es">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Lineamientos para Commits - Guía Profesional</title>
    <meta name="description" content="Guía profesional y completa para la gestión de commits en proyectos de desarrollo de software. Incluye ejemplos de ERP y sistemas POS.">
    <meta name="keywords" content="git, commits, desarrollo de software, guía, convenciones, ERP, POS">
    <meta name="author" content="BorchSolutions">
    <meta property="og:title" content="Lineamientos para Commits - Guía Profesional">
    <meta property="og:description" content="Guía completa para la gestión de commits en proyectos de desarrollo de software.">
    <meta property="og:type" content="website">
    <meta property="og:url" content="https://borchsolutions.github.io/commit-guidelines/">
    <link rel="canonical" href="https://borchsolutions.github.io/commit-guidelines/">
    <!-- Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-4B8M53ZBYE"></script>
    <script>
        window.dataLayer = window.dataLayer || [];

        function gtag() {
            dataLayer.push(arguments);
        }
        gtag('js', new Date());
        gtag('config', 'G-4B8M53ZBYE');
    </script>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tailwindcss/2.2.19/tailwind.min.css">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/prismjs/1.29.0/prism.min.js"></script>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prismjs/1.29.0/themes/prism.min.css">
</head>

<body class="bg-gray-50">
    <div class="container mx-auto px-4 py-8 max-w-4xl">
        <header class="text-center mb-12">
            <h1 class="text-4xl font-bold text-gray-800 mb-4">Lineamientos para Commits</h1>
            <p class="text-xl text-gray-600">Guía de mejores prácticas para la gestión de commits en nuestros proyectos</p>
        </header>

        <main class="space-y-8">
            <!-- Sección 1: Introducción -->
            <section class="bg-white rounded-lg shadow-md p-6">
                <h2 class="text-2xl font-semibold text-gray-800 mb-4">1. Introducción</h2>
                <p class="text-gray-700 mb-4">
                    Este documento establece los lineamientos para la creación de commits en nuestros proyectos de desarrollo. Un commit bien estructurado facilita la revisión de código, mejora la trazabilidad y mantiene un historial claro del proyecto.
                </p>

                <div class="bg-blue-50 border-l-4 border-blue-500 p-4 my-4">
                    <h3 class="font-semibold text-blue-800 mb-2">Principio Fundamental: Commits Atómicos</h3>
                    <p class="text-gray-700">
                        Cada commit debe representar un único cambio lógico en el código. No combines múltiples funcionalidades o correcciones no relacionadas en un solo commit. Esta práctica facilita:
                    </p>
                    <ul class="list-disc ml-6 mt-2 text-gray-700">
                        <li>Revisión de código más eficiente</li>
                        <li>Facilidad para revertir cambios específicos</li>
                        <li>Mejor trazabilidad del historial</li>
                        <li>Integración continua más confiable</li>
                    </ul>
                </div>

                <div class="bg-yellow-50 border-l-4 border-yellow-500 p-4 my-4">
                    <h3 class="font-semibold text-yellow-800">❌ Lo que NO debes hacer:</h3>
                    <pre class="text-sm bg-gray-100 p-2 mt-2 rounded"><code>feat: implementar módulo completo de inutilización de guías

- Crear formulario de ingreso
- Agregar validaciones
- Implementar proceso de aprobación
- Crear reportes
- Actualizar dashboard
- Corregir bugs de interfaz</code></pre>
                    <p class="text-gray-700 mt-2">Este commit mezcla múltiples cambios que deberían estar separados.</p>
                </div>

                <div class="bg-green-50 border-l-4 border-green-500 p-4 my-4">
                    <h3 class="font-semibold text-green-800">✅ La forma correcta:</h3>
                    <p class="text-gray-700 mb-2">Dividir en commits atómicos:</p>
                    <pre class="text-sm bg-gray-100 p-2 rounded"><code>feat(inventory): crear formulario de inutilización de guías
feat(inventory): implementar validaciones de formulario
feat(inventory): agregar flujo de aprobación
feat(inventory): integrar generación de reportes
feat(inventory): añadir widgets en dashboard
fix(inventory): corregir alineación de elementos en móviles</code></pre>
                </div>
            </section>

            <!-- Sección 2: Estructura del Mensaje -->
            <section class="bg-white rounded-lg shadow-md p-6">
                <h2 class="text-2xl font-semibold text-gray-800 mb-4">2. Estructura del Mensaje</h2>
                <div class="bg-gray-100 p-4 rounded-lg mb-4">
                    <pre class="text-sm"><code>tipo(alcance): descripción

[cuerpo opcional]

[nota de pie opcional]</code></pre>
                </div>

                <div class="bg-yellow-50 border-l-4 border-yellow-500 p-4 my-4">
                    <h3 class="font-semibold text-yellow-800 mb-2">Reglas de Formato</h3>
                    <ul class="list-disc ml-6 text-gray-700">
                        <li>Use "/" para indicar jerarquías en el alcance (ej: <code>puntoventa/pago</code>)</li>
                        <li>No use guiones (-) en el alcance</li>
                        <li>No deje espacios entre el tipo y los paréntesis del alcance</li>
                        <li>Use minúsculas para el tipo y alcance</li>
                        <li>La descripción debe comenzar con mayúscula</li>
                        <li>Use siempre <code>feat</code> (no <code>feature</code>) para nuevas características</li>
                    </ul>
                </div>

                <div class="bg-blue-50 border-l-4 border-blue-500 p-4 my-4">
                    <h3 class="font-semibold text-blue-800 mb-2">Nota Importante sobre Tipos de Commit</h3>
                    <p class="text-gray-700">
                        Los tipos de commit están estandarizados para mantener la consistencia y permitir la automatización. Por ejemplo, usamos <code>feat</code> en lugar de <code>feature</code>, <code>fix</code> en lugar de
                        <code>bugfix</code>, etc. Esto facilita la generación automática de changelogs y el mantenimiento del historial de cambios.
                    </p>
                </div>

                <h3 class="text-xl font-semibold text-gray-800 mt-6 mb-3">2.1 Tipos de Commit</h3>
                <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
                    <div class="bg-blue-50 p-4 rounded-lg">
                        <span class="font-bold text-blue-700">feat:</span>
                        <p class="text-gray-700">Nuevas características o funcionalidades</p>
                    </div>
                    <div class="bg-green-50 p-4 rounded-lg">
                        <span class="font-bold text-green-700">fix:</span>
                        <p class="text-gray-700">Corrección de errores</p>
                    </div>
                    <div class="bg-yellow-50 p-4 rounded-lg">
                        <span class="font-bold text-yellow-700">docs:</span>
                        <p class="text-gray-700">Cambios en documentación</p>
                    </div>
                    <div class="bg-purple-50 p-4 rounded-lg">
                        <span class="font-bold text-purple-700">style:</span>
                        <p class="text-gray-700">Cambios de formato, espaciado, etc.</p>
                    </div>
                    <div class="bg-red-50 p-4 rounded-lg">
                        <span class="font-bold text-red-700">refactor:</span>
                        <p class="text-gray-700">Refactorización del código</p>
                    </div>
                    <div class="bg-indigo-50 p-4 rounded-lg">
                        <span class="font-bold text-indigo-700">test:</span>
                        <p class="text-gray-700">Adición o modificación de tests</p>
                    </div>
                </div>
            </section>

            <!-- Sección 3: Ejemplos -->
            <section class="bg-white rounded-lg shadow-md p-6">
                <h2 class="text-2xl font-semibold text-gray-800 mb-4">3. Ejemplos</h2>

                <div class="space-y-4">
                    <div class="bg-gray-100 p-4 rounded-lg">
                        <h4 class="font-semibold text-gray-800 mb-2">Feature: Nuevo Proceso en ERP</h4>
                        <pre class="text-sm"><code>feat(inventory): agregar proceso de inutilización de guías de remisión

- Implementar formulario de inutilización
- Crear validaciones de estado de guía
- Agregar registro de auditoría
- Actualizar menú de navegación en módulo de inventario

Resolves: #789
Área: Módulo de Inventario
Impacto: Permite gestionar guías no utilizadas según normativa</code></pre>
                    </div>

                    <div class="bg-gray-100 p-4 rounded-lg">
                        <h4 class="font-semibold text-gray-800 mb-2">Feature: Componente Específico</h4>
                        <pre class="text-sm"><code>feat(inventory/shipment): crear tabla de guías inutilizadas

- Añadir columnas de fecha, motivo y usuario
- Implementar paginación y filtros
- Agregar acciones de exportación
- Integrar con API de consulta

Related to: #790
Component: RemissionGuideTable</code></pre>
                    </div>

                    <div class="bg-gray-100 p-4 rounded-lg">
                        <h4 class="font-semibold text-gray-800 mb-2">Fix: Corrección en Proceso</h4>
                        <pre class="text-sm"><code>fix(inventory/shipment): corregir validación de guías duplicadas

Se corrigió la validación que permitía inutilizar una guía
más de una vez. Se agregó verificación en base de datos y
mensajes de error apropiados.

Fixes: #791
Impacto: Crítico - Afecta integridad de datos</code></pre>
                    </div>

                    <div class="bg-gray-100 p-4 rounded-lg">
                        <h4 class="font-semibold text-gray-800 mb-2">Refactor: Diseño Responsive</h4>
                        <pre class="text-sm"><code>refactor(pos/ui): adaptar diseño para dispositivos móviles

- Implementar diseño responsive en componente principal
- Ajustar grid de productos para tablets y móviles
- Optimizar menú lateral para vista móvil
- Rediseñar modal de pago para pantallas pequeñas

Devices: Tablets (768px-1024px), Smartphones (<768px)
Testing: Realizado en iOS y Android
Related to: #892 - Mejoras UX en POS</code></pre>
                    </div>

                    <div class="bg-gray-100 p-4 rounded-lg">
                        <h4 class="font-semibold text-gray-800 mb-2">Refactor: Optimización de Componentes</h4>
                        <pre class="text-sm"><code>refactor(pos/components): optimizar rendimiento en dispositivos móviles

- Implementar lazy loading para catálogo de productos
- Reducir tamaño de imágenes para vista móvil
- Optimizar eventos touch y gestos
- Mejorar tiempo de carga inicial

Performance: Bundle size reducido en 45%
Memory Usage: Reducido de 180MB a 95MB en móviles
Related Components: ProductGrid, PaymentModal, SideMenu</code></pre>
                    </div>

                    <div class="bg-gray-100 p-4 rounded-lg">
                        <h4 class="font-semibold text-gray-800 mb-2">Style: Ajustes CSS</h4>
                        <pre class="text-sm"><code>style(pos): implementar media queries y flexbox

- Agregar breakpoints para diferentes dispositivos
- Convertir tablas a diseño flexible
- Ajustar tamaños de fuente y espaciado
- Implementar grid system responsive

CSS Framework: Tailwind
Breakpoints: sm(640px), md(768px), lg(1024px)
Files Modified: pos.css, components/*.css</code></pre>
                    </div>

                    <div class="bg-gray-100 p-4 rounded-lg">
                        <h4 class="font-semibold text-gray-800 mb-2">Docs: Actualización de Documentación</h4>
                        <pre class="text-sm"><code>docs(inventory): actualizar documentación de inutilización de guías

- Agregar diagramas de flujo del proceso
- Incluir ejemplos de casos de uso
- Actualizar manual de usuario
- Documentar APIs relacionadas

Type: Technical Documentation
Ubicación: /docs/inventory/shipment-guides/</code></pre>
                    </div>
                </div>
            </section>

            <!-- Sección 4: Buenas Prácticas -->
            <section class="bg-white rounded-lg shadow-md p-6">
                <h2 class="text-2xl font-semibold text-gray-800 mb-4">4. Buenas Prácticas</h2>

                <div class="mb-6 bg-indigo-50 p-4 rounded-lg">
                    <h3 class="text-xl font-semibold text-indigo-800 mb-3">Principio de Commits Atómicos</h3>
                    <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
                        <div class="bg-white p-4 rounded shadow">
                            <h4 class="font-semibold text-red-600 mb-2">❌ Commit No Atómico:</h4>
                            <p class="text-gray-600 mb-2">Mezclando múltiples cambios:</p>
                            <pre class="text-sm bg-gray-100 p-2 rounded">feat(pos): actualizar módulo de ventas

- Agregar nuevo diseño responsive
- Corregir bug en cálculo de impuestos
- Actualizar librería de UI
- Añadir nueva funcionalidad de descuentos</pre>
                        </div>
                        <div class="bg-white p-4 rounded shadow">
                            <h4 class="font-semibold text-green-600 mb-2">✅ Commits Atómicos:</h4>
                            <p class="text-gray-600 mb-2">Separando cada cambio:</p>
                            <pre class="text-sm bg-gray-100 p-2 rounded">refactor(pos/ui): implementar diseño responsive
fix(pos/tax): corregir cálculo de impuestos
chore(deps): actualizar librería de UI a v2.1
feat(pos/discount): añadir sistema de descuentos</pre>
                        </div>
                    </div>
                </div>

                <div class="space-y-4">
                    <div class="flex items-start space-x-3">
                        <div class="flex-shrink-0 w-6 h-6 rounded-full bg-green-500 flex items-center justify-center text-white">✓</div>
                        <div>
                            <h4 class="font-semibold text-gray-800">Un cambio, un commit</h4>
                            <p class="text-gray-700">Cada commit debe representar una única modificación lógica. Si necesitas describir tu commit con "y", probablemente debas dividirlo.</p>
                        </div>
                    </div>

                    <div class="flex items-start space-x-3">
                        <div class="flex-shrink-0 w-6 h-6 rounded-full bg-green-500 flex items-center justify-center text-white">✓</div>
                        <div>
                            <h4 class="font-semibold text-gray-800">Usa tiempo presente</h4>
                            <p class="text-gray-700">"add feature" en lugar de "added feature"</p>
                        </div>
                    </div>

                    <div class="flex items-start space-x-3">
                        <div class="flex-shrink-0 w-6 h-6 rounded-full bg-green-500 flex items-center justify-center text-white">✓</div>
                        <div>
                            <h4 class="font-semibold text-gray-800">Sé conciso pero descriptivo</h4>
                            <p class="text-gray-700">El título no debe exceder 50 caracteres</p>
                        </div>
                    </div>

                    <div class="flex items-start space-x-3">
                        <div class="flex-shrink-0 w-6 h-6 rounded-full bg-green-500 flex items-center justify-center text-white">✓</div>
                        <div>
                            <h4 class="font-semibold text-gray-800">Incluye el contexto necesario</h4>
                            <p class="text-gray-700">Usa el cuerpo del commit para explicar el "por qué" del cambio</p>
                        </div>
                    </div>

                    <div class="flex items-start space-x-3">
                        <div class="flex-shrink-0 w-6 h-6 rounded-full bg-green-500 flex items-center justify-center text-white">✓</div>
                        <div>
                            <h4 class="font-semibold text-gray-800">Referencias los issues</h4>
                            <p class="text-gray-700">Incluye "Fixes #123" o "Relates to #456" cuando sea relevante</p>
                        </div>
                    </div>

                    <div class="flex items-start space-x-3">
                        <div class="flex-shrink-0 w-6 h-6 rounded-full bg-green-500 flex items-center justify-center text-white">✓</div>
                        <div>
                            <h4 class="font-semibold text-gray-800">Commits frecuentes</h4>
                            <p class="text-gray-700">Realiza commits pequeños y frecuentes en lugar de grandes commits al final del día</p>
                        </div>
                    </div>
                </div>

                <div class="mt-6 bg-yellow-50 p-4 rounded-lg">
                    <h3 class="text-xl font-semibold text-yellow-800 mb-3">¿Cuándo hacer commit?</h3>
                    <ul class="list-disc ml-6 text-gray-700">
                        <li>Después de implementar una nueva función</li>
                        <li>Al terminar una refactorización específica</li>
                        <li>Cuando corriges un bug</li>
                        <li>Al completar una mejora en el diseño</li>
                        <li>Después de actualizar documentación</li>
                        <li>Cuando terminas de escribir tests</li>
                    </ul>
                </div>
            </section>

            <!-- Sección 5: Validador de Commits -->
            <section class="bg-white rounded-lg shadow-md p-6">
                <h2 class="text-2xl font-semibold text-gray-800 mb-4">5. Validador de Commits</h2>

                <div class="space-y-4">
                    <div class="mb-4">
                        <label class="block text-gray-700 font-semibold mb-2">Escribe tu mensaje de commit:</label>
                        <textarea id="commitMessage" class="w-full p-3 border rounded-lg" rows="4"></textarea>
                    </div>
                    <button onclick="validateCommit()" class="bg-blue-500 text-white px-4 py-2 rounded-lg hover:bg-blue-600 transition-colors">
                        Validar Commit
                    </button>
                    <div id="validationResult" class="mt-4"></div>
                </div>
            </section>
        </main>

        <footer class="mt-12 text-center text-gray-600">
            <p>© 2025 BorchSolutions. Todos los derechos reservados.</p>
        </footer>
    </div>

    <script>
        function validateCommit() {
            const commitMessage = document.getElementById('commitMessage').value;
            const resultDiv = document.getElementById('validationResult');

            // Expresión regular actualizada para validar el formato del commit
            const commitRegex = /^(feat|fix|docs|style|refactor|test|chore)(\([a-z][a-z0-9/]*\))?: .{1,50}$/;

            if (!commitMessage) {
                showResult('Por favor, ingresa un mensaje de commit.', 'warning');
                return;
            }

            const firstLine = commitMessage.split('\n')[0];

            if (commitRegex.test(firstLine)) {
                showResult('¡Formato de commit válido! ✅', 'success');
            } else {
                showResult(`El formato del commit no cumple con los lineamientos.
                    Estructura requerida: tipo(alcance): descripción
                    Ejemplo: feat(puntoventa/pago): implementar pago con QR
                    - Usa "/" para jerarquías en el alcance
                    - No uses guiones (-) en el alcance
                    - No dejes espacios entre tipo y paréntesis`, 'error');
            }
        }

        function showResult(message, type) {
            const resultDiv = document.getElementById('validationResult');
            const colors = {
                success: 'bg-green-100 text-green-700 border-green-200',
                error: 'bg-red-100 text-red-700 border-red-200',
                warning: 'bg-yellow-100 text-yellow-700 border-yellow-200'
            };

            resultDiv.className = `p-4 rounded-lg border ${colors[type]}`;
            resultDiv.innerHTML = message.replace(/\n/g, '<br>');
        }
    </script>
</body>

</html>