mirror of
https://github.com/microsoft/Web-Dev-For-Beginners.git
synced 2025-08-13 18:24:33 +02:00
Merge branch 'main' of https://github.com/microsoft/Web-Dev-For-Beginners
This commit is contained in:
Sanjay
@@ -2,7 +2,7 @@
|
||||
|
||||
This lesson covers the basics of GitHub, a platform to host and manage changes to your code.
|
||||
|
||||
|
||||
|
||||
> Sketchnote by [Tomomi Imura](https://twitter.com/girlie_mac)
|
||||
|
||||
## Pre-Lecture Quiz
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.6 MiB |
@@ -1,6 +1,9 @@
|
||||
# Introducción a GitHub
|
||||
|
||||
Esta lección cubre los conceptos básicos de GitHub, una plataforma para alojar y administrar cambios en su código.
|
||||
Esta lección cubre los conceptos básicos de GitHub, una plataforma para alojar y administrar cambios en tu código.
|
||||
|
||||
|
||||
> Sketchnote by [Tomomi Imura](https://twitter.com/girlie_mac)
|
||||
|
||||
## [Pre-lecture prueba](https://nice-beach-0fe9e9d0f.azurestaticapps.net/quiz/3)
|
||||
|
||||
@@ -8,64 +11,64 @@ Esta lección cubre los conceptos básicos de GitHub, una plataforma para alojar
|
||||
|
||||
En esta lección, cubriremos:
|
||||
|
||||
- seguimiento del trabajo que realiza en su máquina
|
||||
- dando seguimiento al trabajo que realizas en tu máquina
|
||||
- trabajar en proyectos con otros
|
||||
- cómo contribuir al software de código abierto
|
||||
- cómo contribuir al software de código abierto (open source)
|
||||
|
||||
### Prerrequisitos
|
||||
|
||||
Antes de comenzar, deberá verificar si Git está instalado. En el tipo de terminal:
|
||||
Antes de comenzar, verifica si Git está instalado. Escribe en tu terminal:
|
||||
`git --version`
|
||||
|
||||
Si Git no está instalado, [descargar Git](https://git-scm.com/downloads). Luego, configure su perfil de Git local en la terminal:
|
||||
Si Git no está instalado, [descarga Git aquí](https://git-scm.com/downloads). Luego, configura tu perfil de Git local en la terminal:
|
||||
`git config --global user.name "tu-nombre"`
|
||||
`git config --global user.email "tu-email"`
|
||||
|
||||
Para comprobar si Git ya está configurado, puede escribir:
|
||||
Para comprobar si Git ya está configurado, escribe:
|
||||
`git config --list`
|
||||
|
||||
También necesitará una cuenta de GitHub, un editor de código (como Visual Studio Code) y deberá abrir su terminal (o: símbolo del sistema).
|
||||
También necesitarás una cuenta de GitHub, un editor de código (como Visual Studio Code) y deberás abrir tu terminal.
|
||||
|
||||
Vaya a [github.com](https://github.com/) y cree una cuenta si aún no lo ha hecho, o inicie sesión y complete su perfil.
|
||||
Ve a [github.com](https://github.com/) y crea una cuenta si aún no lo has hecho, o inicia sesión y completa tu perfil.
|
||||
|
||||
✅ GitHub no es el único repositorio de código del mundo; hay otros, pero GitHub es el más conocido.
|
||||
|
||||
### Preparación
|
||||
|
||||
Necesitará una carpeta con un proyecto de código en su máquina local (computadora portátil o PC) y un repositorio público en GitHub, que le servirá como ejemplo de cómo contribuir a los proyectos de otros.
|
||||
Necesitarás una directorio con un proyecto de código en tu máquina local (computadora portátil o PC) y un repositorio público en GitHub, que te servirá como ejemplo de cómo contribuir a los proyectos de otros.
|
||||
|
||||
---
|
||||
|
||||
## Gestión de código
|
||||
|
||||
Digamos que tiene una carpeta localmente con algún proyecto de código y desea comenzar a rastrear su progreso usando git, el sistema de control de versiones. Algunas personas comparan el uso de git con escribir una carta de amor a su yo futuro. Al leer sus mensajes de confirmación días, semanas o meses después, podrá recordar por qué tomó una decisión o "revertir" un cambio, es decir, cuando escribe buenos "mensajes de confirmación".
|
||||
Digamos que tienes una directorio local con algún proyecto de código y deseas rastrear tu progreso usando git, el sistema de control de versiones. Algunas personas comparan el uso de git con escribir una carta de amor a tu futuro. Al leer tus mensajes de confirmación días, semanas o meses después, podrás recordar por qué tomaste una decisión o "revertiste" un cambio, es decir, cuando escribes buenos "mensajes de confirmación".
|
||||
|
||||
### Tarea: hacer un repositorio y enviar código
|
||||
### Tarea: hacer un repositorio git y enviar código
|
||||
|
||||
1. **Crear repositorio en GitHub**. En GitHub.com, en la pestaña de repositorios, o en la barra de navegación superior derecha, busque el botón **nuevo repositorio**.
|
||||
1. **Crear repositorio en GitHub**. En GitHub.com, en la pestaña de repositorios, o en la barra de navegación superior derecha, busca el botón **nuevo repositorio**.
|
||||
|
||||
1. Dale un nombre a tu repositorio (carpeta)
|
||||
1. Seleccione **crear repositorio**.
|
||||
1. Dale un nombre a tu repositorio (directorio)
|
||||
1. Selecciona **crear repositorio**.
|
||||
|
||||
1. **Navegue a su carpeta de trabajo**. En su terminal, cambie a la carpeta (también conocida como directorio) que desea comenzar a rastrear. Tipo:
|
||||
1. **Navegue a su directorio de trabajo**. En tu terminal, cambia a la directorio (también conocida como directorio) que deseas comenzar a rastrear. Escribe:
|
||||
|
||||
```bash
|
||||
cd [nombre de tu carpeta]
|
||||
cd [nombre de tu directorio]
|
||||
```
|
||||
|
||||
1. **Inicializar un repositorio de git**. En su tipo de proyecto:
|
||||
1. **Inicializar un repositorio de git**. En tu proyecto escribe:
|
||||
|
||||
```bash
|
||||
git init
|
||||
```
|
||||
|
||||
1. **Comprobar estado**. Para comprobar el estado de su tipo de repositorio:
|
||||
1. **Comprobar estado**. Para checar el estado del proyecto escribe:
|
||||
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
|
||||
la salida puede verse así:
|
||||
La respuesta de la terminal (CLI) probablemente se verá así:
|
||||
|
||||
```output
|
||||
Changes not staged for commit:
|
||||
@@ -76,7 +79,7 @@ Digamos que tiene una carpeta localmente con algún proyecto de código y desea
|
||||
modified: file2.txt
|
||||
```
|
||||
|
||||
Por lo general, un comando `git status` le dice cosas como qué archivos están listos para ser guardados en el repositorio o tiene cambios que es posible que desee conservar.
|
||||
Por lo general, un comando `git status` te dice cosas como qué archivos están listos para ser guardados en el repositorio o cambios en tu codigo que puedes conservar.
|
||||
|
||||
1. **Agregar archivos al seguimiento**
|
||||
|
||||
@@ -84,27 +87,25 @@ Digamos que tiene una carpeta localmente con algún proyecto de código y desea
|
||||
git add .
|
||||
```
|
||||
|
||||
El argumento `git add` más `.` indica que todos sus archivos y cambios para el seguimiento.
|
||||
El argumento `git add` más `.` indica que todos tus archivos y cambios están listos para darles seguimiento.
|
||||
|
||||
1. **Persistir en tu trabajo**. En este punto, ha agregado los archivos a lo que se denomina _área de preparación_. Un lugar donde Git rastrea sus archivos. Para que el cambio sea permanente, debe _commitir_ los archivos. Para hacerlo, crea un _commit_ con el comando `git commit`. Un _commit_ representa un punto de ahorro en el historial de su repositorio. Escriba lo siguiente para crear un _commit_:
|
||||
1. **Persistir en tu trabajo**. En este punto, has agregado los archivos a lo que se denomina _área de preparación_. Un lugar donde Git rastrea tus archivos. Para que el cambio sea permanente, debes _commitir_ los archivos. Para hacerlo, creas un _commit_ con el comando `git commit`. Un _commit_ representa un punto en el historial de tu repositorio que estás guardando. Escribe lo siguiente para crear un _commit_:
|
||||
|
||||
```bash
|
||||
git commit -m "first commit"
|
||||
```
|
||||
|
||||
Esto confirma todos sus archivos, agregando el mensaje "primer compromiso". Para futuros mensajes de confirmación, querrá ser más descriptivo en su descripción para transmitir qué tipo de cambio ha realizado.
|
||||
Esto confirma todos tus archivos, agregando el mensaje "primer compromiso". Para futuros mensajes de confirmación, querrás ser más descriptivo en tu descripción para transmitir qué tipo de cambio has realizado.
|
||||
|
||||
1. **Conecte su repositorio de Git local con GitHub**. Un repositorio de Git es bueno en su máquina, pero en algún momento desea tener una copia de seguridad de sus archivos en algún lugar y también invitar a otras personas a trabajar con usted en su repositorio. Un gran lugar para hacerlo es GitHub. Recuerde que ya hemos creado un repositorio en GitHub, por lo que lo único que debemos hacer es conectar nuestro repositorio de Git local con GitHub. El comando `git remote add` hará precisamente eso. Escriba el siguiente comando:
|
||||
|
||||
|
||||
> Tenga en cuenta que antes de escribir el comando, vaya a la página de su repositorio de GitHub para encontrar la URL del repositorio. Lo usará en el siguiente comando. Reemplaza `repository_name` con tu URL de GitHub.
|
||||
1. **Conecta tu repositorio de Git local con GitHub**. Es bueno tener un repositorio de Git en tu máquina, pero también tienes que guarder todos sus archivos en algún lugar e invitar a otras personas a trabajar contigo en tu repositorio. Un buen lugar para hacerlo es GitHub. Recuerda que ya hemos creado un repositorio en GitHub, por lo que lo único que debemos hacer es conectar nuestro repositorio de Git local con GitHub. El comando `git remote add` hará precisamente eso. Escribe el siguiente comando:
|
||||
|
||||
> Nota, antes de escribir el comando, ve a la página de tu repositorio de GitHub para encontrar el URL del repositorio. Lo usarás en el siguiente comando. Reemplaza `repository_name` con tu URL de GitHub.
|
||||
|
||||
```bash
|
||||
git remote add origin https://github.com/username/repository_name.git
|
||||
```
|
||||
|
||||
Esto crea un _remote_, o conexión, llamado "origin" que apunta al repositorio de GitHub que creó anteriormente.
|
||||
Esto crea un _remote_, o conexión, llamado "origin" que apunta al repositorio de GitHub que creaste anteriormente.
|
||||
|
||||
1. **Envía archivos locales a GitHub**. Hasta ahora ha creado una _conexión_ entre el repositorio local y el repositorio de GitHub. Enviemos estos archivos a GitHub con el siguiente comando `git push`, así:
|
||||
|
||||
@@ -113,9 +114,9 @@ Digamos que tiene una carpeta localmente con algún proyecto de código y desea
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
Esto envía sus confirmaciones en su rama "principal" a GitHub.
|
||||
Esto envía una confirmación en tu rama "principal" a GitHub.
|
||||
|
||||
1. **Para agregar más cambios**. Si desea continuar haciendo cambios y enviarlos a GitHub, solo necesitará usar los siguientes tres comandos:
|
||||
1. **Para agregar más cambios**. Si deseas continuar haciendo cambios y enviarlos a GitHub, solo necesitas usar los siguientes tres comandos:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
@@ -123,83 +124,84 @@ Digamos que tiene una carpeta localmente con algún proyecto de código y desea
|
||||
git push
|
||||
```
|
||||
|
||||
> Sugerencia: es posible que también desee adoptar un archivo `.gitignore` para evitar que los archivos que no desea rastrear aparezcan en GitHub, como el archivo de notas que almacena en la misma carpeta pero no tiene lugar para escribir su mensaje de confirmación aquí repositorio público. Puede encontrar plantillas para archivos `.gitignore` en [.gitignore templates](github.com/github/gitignore).
|
||||
> Sugerencia: es posible que también desees adoptar un archivo `.gitignore` para evitar que los archivos que no deseas rastrear aparezcan en GitHub. Puedes encontrar plantillas para archivos `.gitignore` en [.gitignore templates](github.com/github/gitignore).
|
||||
|
||||
|
||||
#### Confirmar mensajes
|
||||
|
||||
Una gran línea de asunto de confirmación de Git completa la siguiente oración:
|
||||
Una buena línea de asunto (subject line) de confirmación de Git completa la siguiente oración:
|
||||
Si se aplica, esta confirmación será <su línea de asunto aquí>
|
||||
|
||||
Para el sujeto use el imperativo, tiempo presente: "cambiar" no "cambiar" ni "cambiar".
|
||||
Para el sujeto use el imperativo, tiempo presente: "cambiar" no "cambió" ni "cambiara".
|
||||
Como en el sujeto, en el cuerpo (opcional) también use el imperativo, presente. El cuerpo debe incluir la motivación para el cambio y contrastarla con la conducta anterior. Estás explicando el "por qué", no el "cómo".
|
||||
|
||||
✅ Tómate unos minutos para navegar por GitHub. ¿Puedes encontrar un mensaje de compromiso realmente bueno? ¿Puedes encontrar uno realmente mínimo? ¿Qué información crees que es la más importante y útil de transmitir en un mensaje de compromiso?
|
||||
|
||||
### Tarea: Colaborar
|
||||
|
||||
|
||||
La razón principal para poner cosas en GitHub fue hacer posible la colaboración con otros desarrolladores.
|
||||
|
||||
## Trabajando en proyectos con otros
|
||||
|
||||
En su repositorio, vaya a `Insights > Community` para ver cómo se compara su proyecto con los estándares comunitarios recomendados.
|
||||
En tu repositorio, ve a `Insights > Community` para ver cómo se compara tu proyecto con los estándares comunitarios recomendados.
|
||||
|
||||
Aquí hay algunas cosas que pueden mejorar su repositorio de GitHub:
|
||||
Aquí hay algunas cosas que pueden mejorar tu repositorio de GitHub:
|
||||
- **Descripción**. ¿Agregaste una descripción para tu proyecto?
|
||||
- **README**. ¿Agregaste un archivo README? GitHub proporciona una guía para escribir un [README](https://docs.github.com/articles/about-readmes/).
|
||||
- **Pauta de contribución**. ¿Su proyecto tiene [pautas de contribución](https://docs.github.com/articles/setting-guidelines-for-repository-contributors/),
|
||||
- **Código de Conducta**. un [Código de conducta](https://docs.github.com/articles/adding-a-code-of-conduct-to-your-project/),
|
||||
- **Licencia**. Quizás lo más importante, una [licencia](https://docs.github.com/articles/adding-a-license-to-a-repository/)?
|
||||
- **Guía de contribución**. ¿Tiene [guías de contribución](https://docs.github.com/articles/setting-guidelines-for-repository-contributors/) tu proyecto?
|
||||
- **Código de Conducta**. Crea un [Código de conducta](https://docs.github.com/articles/adding-a-code-of-conduct-to-your-project/).
|
||||
- **Licencia**. Quizás lo más importante, una [licencia](https://docs.github.com/articles/adding-a-license-to-a-repository/).
|
||||
|
||||
Todos estos recursos beneficiarán la incorporación de nuevos miembros del equipo. Y esos son típicamente el tipo de cosas que los nuevos colaboradores miran antes incluso de mirar su código, para descubrir si su proyecto es el lugar adecuado para que ellos pasen su tiempo.
|
||||
Todos estos recursos beneficiarán la incorporación de nuevos miembros del equipo. Y esos son típicamente el tipo de cosas que los nuevos colaboradores miran antes incluso de mirar tu código, para descubrir si tu proyecto es el lugar adecuado para que ellos pasen su tiempo.
|
||||
|
||||
✅ Los archivos README, aunque requieren tiempo para prepararse, a menudo son descuidados por los ocupados mantenedores. ¿Puede encontrar un ejemplo de uno particularmente descriptivo? Nota: hay algunas [herramientas para ayudar a crear buenos archivos READMEs](https://www.makeareadme.com/) que le gustaría probar.
|
||||
✅ Los archivos README, aunque requieren tiempo para prepararse, a menudo son descuidados por los mantenedores. ¿Puedes encontrar un ejemplo de uno particularmente descriptivo? Nota: aquí hay algunas [herramientas para ayudar a crear buenos archivos READMEs](https://www.makeareadme.com/) que te puedes probar.
|
||||
|
||||
|
||||
### Tarea: Fusionar código
|
||||
### Tarea: Fusionar (merging) código
|
||||
|
||||
Los documentos que contribuyen ayudan a las personas a contribuir al proyecto. Explica qué tipos de contribuciones está buscando y cómo funciona el proceso. Los colaboradores deberán seguir una serie de pasos para poder contribuir a su repositorio en GitHub:
|
||||
Los documentos que contribuyes ayudan a las personas a contribuir al proyecto. Explica qué tipos de contribuciones estás buscando y cómo funciona el proceso. Los colaboradores deberán seguir una serie de pasos para poder contribuir a tu repositorio en GitHub:
|
||||
|
||||
1. **Bifurcando su repositorio** Probablemente querrá que la gente _bifurque_ su proyecto. Bifurcar significa crear una réplica de su repositorio en su perfil de GitHub.
|
||||
1. **Bifurcando (forking) tu repositorio** Probablemente querrás que la gente _bifurque_ (fork) tu proyecto. Bifurcar significa crear una réplica de tu repositorio en su perfil de GitHub.
|
||||
1. **Clonar**. Desde allí, clonarán el proyecto en su máquina local.
|
||||
1. **Crea una rama**. Querrá pedirles que creen una _ rama_ para su trabajo.
|
||||
1. **Concentre su cambio en un área**. Pida a los colaboradores que concentren sus contribuciones en una cosa a la vez; de esa manera, las posibilidades de que pueda _fusionar_ en su trabajo son mayores. Imagine que escriben una corrección de errores, agregan una nueva función y actualizan varias pruebas; ¿qué sucede si lo desea o solo puede implementar 2 de 3 o 1 de 3 cambios?
|
||||
1. **Crear una rama**. Querrás pedirles que creen una _ rama_ para su trabajo.
|
||||
1. **Concentre su cambio en un área**. Pida a los colaboradores que concentren sus contribuciones en una cosa a la vez; de esa manera, las posibilidades de _fusionar_ su trabajo son mayores. Imagínate que escriben una corrección de errores, agregan una nueva función y actualizan varias pruebas; ¿qué sucede si quieres todos los cambios o solo puedes implementar 2 de 3 o 1 de 3 cambios?
|
||||
|
||||
✅ Imagine una situación en la que las sucursales son particularmente críticas para escribir y enviar un buen código. ¿En qué casos de uso se te ocurren?
|
||||
✅ Imagínate una situación en la que las ramas (branches) de git son particularmente críticas para escribir y enviar buen código. ¿Qué casos de uso se te ocurren?
|
||||
|
||||
> Tenga en cuenta que sea el cambio que desea ver en el mundo y cree también sucursales para su propio trabajo. Todas las confirmaciones que realice se realizarán en la sucursal en la que está actualmente "registrado". Use `git status` para ver qué rama es esa.
|
||||
> Se el cambio que deseas ver en el mundo y crea también ramas para tu propio trabajo. Todas las confirmaciones que realices se realizarán en la rama en la que estás actualmente "registrado". Usa `git status` para ver qué rama es.
|
||||
|
||||
Repasemos el flujo de trabajo de un colaborador. Suponga que el colaborador ya ha _bifurcado_ y _clonado_ el repositorio para que tenga un repositorio de Git listo para trabajar en su máquina local:
|
||||
Repasemos el flujo de trabajo de un colaborador. Supon que el colaborador ya ha _bifurcado_ y _clonado_ el repositorio para que tenga un repositorio de Git listo para trabajar en su máquina local:
|
||||
|
||||
1. **Crea una rama**. Use el comando `git branch` para crear una rama que contendrá los cambios que pretenden contribuir:
|
||||
1. **Crea una rama**. Usa el comando `git branch` para crear una rama que tendrá los cambios que quieres contribuir:
|
||||
|
||||
```bash
|
||||
git branch [branch-name]
|
||||
```
|
||||
|
||||
1. **Cambiar a rama de trabajo**. Cambie a la rama especificada y actualice el directorio de trabajo con `git checkout`:
|
||||
1. **Cambiar a rama de trabajo**. Cambia a la rama especificada y actualiza tu directorio de trabajo con `git checkout`:
|
||||
|
||||
```bash
|
||||
git checkout [branch-name]
|
||||
```
|
||||
|
||||
1. **Trabaja**. En este punto, desea agregar sus cambios. No olvide informarle a Git con los siguientes comandos:
|
||||
1. **Trabaja**. En este punto, deseas agregar tus cambios. No olvides informarle a Git con los siguientes comandos:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "mis cambios"
|
||||
```
|
||||
|
||||
Asegúrese de darle un buen nombre a su compromiso, por su bien y por el mantenedor del repositorio en el que está ayudando.
|
||||
Asegúrate de darle un buen nombre a tu commit, tanto por tu bien como por el mantenedor del repositorio en el que estás ayudando.
|
||||
|
||||
1. **Combine su trabajo con la rama `principal`**. En algún momento ha terminado de trabajar y desea combinar su trabajo con el de la rama `principal`. La rama `main` podría haber cambiado mientras tanto, así que asegúrese de actualizarla primero a la última con los siguientes comandos:
|
||||
1. **Combina tu trabajo con la rama `principal`**. En algún momento has terminado de trabajar y deseas combinar tu trabajo con el de la rama `principal`. La rama `main` podría haber cambiado mientras tanto, así que asegúrate de actualizarla con los siguientes comandos:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull
|
||||
```
|
||||
|
||||
En este punto, querrá asegurarse de que cualquier _conflicto_, situaciones en las que Git no pueda _combinarse_ fácilmente los cambios, ocurra en su rama de trabajo. Por lo tanto, ejecute los siguientes comandos:
|
||||
En este punto, querrás asegurarte de que cualquier _conflicto_, situaciones en las que Git no pueda _combinarse_ fácilmente los cambios, ocurren en tu rama de trabajo. Mientras tanto, ejecuta los siguientes comandos:
|
||||
|
||||
```bash
|
||||
git checkout [branch_name]
|
||||
@@ -208,69 +210,69 @@ Repasemos el flujo de trabajo de un colaborador. Suponga que el colaborador ya h
|
||||
|
||||
Esto traerá todos los cambios de `main` a su rama y es de esperar que pueda continuar. De lo contrario, VS Code le dirá dónde está _confundido_ Git y simplemente modificará los archivos afectados para decir qué contenido es el más preciso.
|
||||
|
||||
1. **Envíe su trabajo a GitHub**. Enviar tu trabajo a GitHub significa dos cosas. Empujar su sucursal a su repositorio y luego abrir un PR, Pull Request.
|
||||
1. **Envía tu trabajo a GitHub**. Enviar tu trabajo a GitHub significa dos cosas. Empujar tu rama a tu repositorio y luego abrir un PR (Pull Request).
|
||||
|
||||
```bash
|
||||
git push --set-upstream origin [branch-name]
|
||||
```
|
||||
|
||||
El comando anterior crea la rama en su repositorio bifurcado.
|
||||
El comando anterior crea la rama en tu repositorio bifurcado.
|
||||
|
||||
1. **Abra una PR**. A continuación, desea abrir un PR. Para hacerlo, navegue al repositorio bifurcado en GitHub. Verá una indicación en GitHub donde le preguntará si desea crear un nuevo PR, haga clic en eso y lo llevará a una interfaz donde puede cambiar el título del mensaje de confirmación, asígnele una descripción más adecuada. Ahora, el mantenedor del repositorio que bifurcó verá este PR y _dedos cruzados_ apreciarán y _ fusionar_ su PR. Ahora eres un colaborador, yay :)
|
||||
1. **Abre un PR**. A continuación, abre un PR. Para hacerlo, navega al repositorio bifurcado en GitHub. Verás una indicación en GitHub donde te preguntarán si deseas crear un nuevo PR. Haz clic en eso y lo llevará a una interfaz donde puedes cambiar el título del mensaje de confirmación, asignarle una descripción más adecuada. Ahora, el mantenedor del repositorio que bifurcaste verá este PR y _dedos cruzados_ apreciarán y _ fusionarán_ tu PR. Ahora eres un colaborador, yay :)
|
||||
|
||||
1. **Limpiar**. Se considera una buena práctica _limpiar_ después de ti. Desea limpiar tanto su sucursal local como la sucursal que envió a GitHub. Primero eliminémoslo localmente con el siguiente comando:
|
||||
1. **Limpiar**. Se considera una buena práctica _limpiar_ después de ti. Limpiar tanto tu rama local como la rama que enviaste a GitHub. Primero eliminémoslo localmente con el siguiente comando:
|
||||
|
||||
```bash
|
||||
git branch -d [branch-name]
|
||||
```
|
||||
|
||||
Asegúrese de ir a la página de GitHub para el repositorio bifurcado a continuación y elimine la rama remota que acaba de ingresar.
|
||||
Asegúrate de ir a la página de GitHub del repositorio bifurcado a continuación y elimina la rama remota que acabas de ingresar.
|
||||
|
||||
`Solicitud de extracción` parece un término tonto porque realmente desea impulsar los cambios al proyecto. Pero el mantenedor (propietario del proyecto) o el equipo central debe considerar sus cambios antes de fusionarlo con la rama "principal" del proyecto, por lo que realmente está solicitando una decisión de cambio a un mantenedor.
|
||||
`Solicitud de extracción` parece un término tonto porque realmente deseas impulsar los cambios al proyecto. Pero el mantenedor (propietario del proyecto) o el equipo central debe considerar tus cambios antes de fusionarlo con la rama "principal" del proyecto, por lo que realmente estás solicitando una decisión de cambio a un mantenedor.
|
||||
|
||||
Una solicitud de extracción es el lugar para comparar y discutir las diferencias introducidas en una rama con revisiones, comentarios, pruebas integradas y más. Una buena solicitud de extracción sigue aproximadamente las mismas reglas que un mensaje de confirmación. Puede agregar una referencia a un problema en el rastreador de problemas, cuando su trabajo, por ejemplo, soluciona un problema. Esto se hace usando un '#' seguido del número de su problema. Por ejemplo, `#97`.
|
||||
Una solicitud de extracción es el lugar para comparar y discutir las diferencias introducidas en una rama con revisiones, comentarios, pruebas integradas y más. Una buena solicitud de extracción sigue aproximadamente las mismas reglas que un mensaje de confirmación. Puedes agregar una referencia a un problema en el rastreador de problemas, cuando tu trabajo, por ejemplo, soluciona un problema. Esto se hace usando un '#' seguido del número de tu problema. Por ejemplo, `#97`.
|
||||
|
||||
🤞 Cruce los dedos para que todos los controles pasen y los propietarios del proyecto combinen sus cambios en el proyecto🤞
|
||||
🤞 Cruza los dedos para que todos los controles pasen y los propietarios del proyecto combinen tus cambios en el proyecto🤞
|
||||
|
||||
Actualice su rama de trabajo local actual con todas las nuevas confirmaciones de la rama remota correspondiente en GitHub:
|
||||
Actualice tu rama de trabajo local actual con todas las nuevas confirmaciones de la rama remota correspondiente en GitHub:
|
||||
|
||||
`git pull`
|
||||
|
||||
## Cómo contribuir al código abierto
|
||||
|
||||
Primero, busquemos un repositorio (o: repositorio) en GitHub que le interese y al que le gustaría contribuir con un cambio. Querrá copiar el contenido de a nuestra máquina.
|
||||
Primero, busquemos un repositorio en GitHub que te interese y al que te gustaría contribuir con un cambio. Querrás copiar el contenido a nuestra máquina.
|
||||
|
||||
✅ Una buena forma de encontrar repositorios 'aptos para principiantes' es [buscar por la etiqueta `buena-primera-edición`](https://github.blog/2020-01-22-browse-good-first-issues-para-empezar-a-contribuir-al-código-abierto/).
|
||||
|
||||
Hay varias formas de copiar código. Una forma es "clonar" el contenido del repositorio, usando HTTPS, SSH o usando GitHub CLI (Interfaz de línea de comandos).
|
||||
|
||||
Abra su terminal y clone el repositorio así:
|
||||
Abre tu terminal y clona el repositorio así:
|
||||
`git clone https://github.com/ProjectURL`
|
||||
|
||||
Para trabajar en el proyecto, cambie a la carpeta correcta:
|
||||
Para trabajar en el proyecto, cambia al directorio correcto:
|
||||
`cd ProjectURL`
|
||||
|
||||
También puede abrir todo el proyecto utilizando [Codespaces](https://github.com/features/codespaces), el entorno de desarrollo en la nube / editor de código integrado de GitHub o [GitHub Desktop](https://desktop.github.com/).
|
||||
También puedes abrir todo el proyecto utilizando [Codespaces](https://github.com/features/codespaces), el entorno de desarrollo en la nube / editor de código integrado de GitHub o [GitHub Desktop](https://desktop.github.com/).
|
||||
|
||||
Por último, puede descargar el código en una carpeta comprimida.
|
||||
Por último, puedes descargar el código en un directorio comprimido.
|
||||
|
||||
### Algunas cosas más interesantes sobre GitHub
|
||||
|
||||
Puede destacar, ver y / o "fork" cualquier repositorio público en GitHub. Puede encontrar sus repositorios destacados en el menú desplegable de la parte superior derecha. Es como marcar como favorito, pero por código.
|
||||
Puede destacar, ver y / o "fork" cualquier repositorio público en GitHub. Puedes encontrar tus repositorios destacados en el menú desplegable de la parte superior derecha. Es como marcar como favorito, pero por código.
|
||||
|
||||
Los proyectos tienen un rastreador de problemas, principalmente en GitHub en la pestaña "Issues" a menos que se indique lo contrario, donde las personas debaten los problemas relacionados con el proyecto. Y la pestaña Solicitudes de extracción es donde las personas debaten y revisan los cambios que están en curso.
|
||||
|
||||
Los proyectos también pueden tener discusiones en foros, listas de correo o canales de chat como Slack, Discord o IRC.
|
||||
|
||||
✅ Eche un vistazo a su nuevo repositorio de GitHub y pruebe algunas cosas, como editar la configuración, agregar información a su repositorio y crear un proyecto (como un tablero Kanban). ¡Hay muchas cosas que puedes hacer!
|
||||
✅ Echa un vistazo a tu nuevo repositorio de GitHub y prueba algunas cosas, como editar la configuración, agregar información a tu repositorio y crear un proyecto (como un tablero Kanban). ¡Hay muchas cosas que puedes hacer!
|
||||
|
||||
🚀 Desafío: empareje con un amigo para trabajar en el código del otro. Cree un proyecto de forma colaborativa, bifurque el código, cree ramas y combine los cambios.
|
||||
🚀 Desafío: empareja con un amigo(a) para trabajar en el código juntos. Crea un proyecto de forma colaborativa, bifurque el código, crea ramas y combina los cambios.
|
||||
|
||||
## [Post-lecture prueba](https://nice-beach-0fe9e9d0f.azurestaticapps.net/quiz/4)
|
||||
|
||||
## Revisión y autoestudio
|
||||
|
||||
Obtenga más información sobre [contribución al software de código abierto](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution).
|
||||
Obtén más información sobre [contribución al software de código abierto](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution).
|
||||
|
||||
[Hoja de referencia de Git](https://training.github.com/downloads/github-git-cheat-sheet/).
|
||||
|
||||
@@ -278,6 +280,6 @@ Práctica práctica práctica. GitHub tiene excelentes rutas de aprendizaje disp
|
||||
|
||||
- [Primera semana en GitHub](https://lab.github.com/githubtraining/first-week-on-github)
|
||||
|
||||
También encontrará laboratorios más avanzados.
|
||||
También encontrarás laboratorios más avanzados.
|
||||
|
||||
**Tarea**: Completa [la primera semana en el laboratorio de capacitación de GitHub](https://lab.github.com/githubtraining/first-week-on-github)
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Pelajaran ini mencakup dasar-dasar GitHub, platform untuk menghosting dan mengelola perubahan pada kode Anda.
|
||||
|
||||
|
||||
|
||||
> Catatan sketsa oleh [Tomomi Imura](https://twitter.com/girlie_mac)
|
||||
|
||||
## Kuis Pra-Kuliah
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Questa lezione tratta delle basi di GitHub, una piattaforma per ospitare e gestire modifiche al proprio codice.
|
||||
|
||||
|
||||
|
||||
> Sketchnote by [Tomomi Imura](https://twitter.com/girlie_mac)
|
||||
|
||||
## Quiz Pre-lezione
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
이 강의에서는 코드 변경점을 호스팅하고 관리하는 플랫폼인 GitHub의 기본 사항을 다룹니다.
|
||||
|
||||
|
||||
|
||||
> Sketchnote by [Tomomi Imura](https://twitter.com/girlie_mac)
|
||||
|
||||
## 강의 전 퀴즈
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Pelajaran ini merangkumi pengetahuan asas tentang GitHub, dan adalah salah satu platform untuk menjadi tuan rumah dan menguruskan perubahan pada kod anda.
|
||||
|
||||
|
||||
|
||||
> Sketchnote by [Tomomi Imura](https://twitter.com/girlie_mac)
|
||||
|
||||
## Kuiz Pra-Kuliah
|
||||
|
||||
@@ -0,0 +1,318 @@
|
||||
# Inleiding van GitHub
|
||||
|
||||
Deze les behandelt de basisprincipes van GitHub, een platform voor het hosten en beheren van wijzigingen in uw code.
|
||||
|
||||
|
||||
> Sketchnote by [Tomomi Imura](https://twitter.com/girlie_mac)
|
||||
|
||||
## Quiz voorafgaand aan de lezing
|
||||
[Quiz voorafgaand aan de lezing](https://nice-beach-0fe9e9d0f.azurestaticapps.net/quiz/3)
|
||||
|
||||
## Inleiding
|
||||
|
||||
In deze les behandelen we:
|
||||
|
||||
- het volgen van het werk dat u op uw machine doet
|
||||
- samen met anderen aan projecten werken
|
||||
- hoe u kunt bijdragen aan open source software
|
||||
|
||||
### Vereisten
|
||||
|
||||
Voordat u begint, moet u controleren of Git is geïnstalleerd. In het terminal typ:
|
||||
`git --version`
|
||||
|
||||
Als Git niet is geïnstalleerd, [download Git](https://git-scm.com/downloads). Stel vervolgens uw lokale Git-profiel in de terminal in:
|
||||
* `git config --global user.name "uw-naam"`
|
||||
* `git config --global user.email "uw-email"`
|
||||
|
||||
Om te controleren of Git al is geconfigureerd, kunt u het volgende typen:
|
||||
`git config --list`
|
||||
|
||||
U heeft ook een GitHub-account nodig, een code-editor (zoals Visual Studio Code) en u moet uw terminal openen (of: command prompt).
|
||||
|
||||
Navigeer naar [github.com](https://github.com/) en maak een account aan als u dat nog niet heeft gedaan, of log in en vul uw profiel in.
|
||||
|
||||
✅ GitHub is niet de enige coderepository ter wereld; er zijn anderen, maar GitHub is de bekendste
|
||||
|
||||
### Voorbereiding
|
||||
|
||||
U heeft zowel een map met een codeproject op uw lokale computer (laptop of pc) als een openbare repository op GitHub nodig, die als voorbeeld zal dienen voor hoe u kunt bijdragen aan de projecten van anderen.
|
||||
|
||||
---
|
||||
|
||||
## Code beheer
|
||||
|
||||
Laten we zeggen dat u lokaal een map hebt met een of ander codeproject en u wilt beginnen met het volgen van uw voortgang met git - het versiebeheersysteem. Sommige mensen vergelijken het gebruik van git met het schrijven van een liefdesbrief aan uw toekomstige zelf. Als u uw commitberichten dagen of weken of maanden later leest, zult u u kunnen herinneren waarom u een beslissing heeft genomen, of een wijziging "terugdraaien" - dat wil zeggen, wanneer u goede "commitberichten" schrijft.
|
||||
|
||||
### Taak: maak een repository en leg code vast
|
||||
|
||||
1. **Maak een repository op GitHub**. Zoek op GitHub.com, in het tabblad repositories, of in de navigatiebalk rechtsboven, de knop **new repo**.
|
||||
|
||||
1. Geef uw repository (map) een naam
|
||||
1. Selecteer **create repository**.
|
||||
|
||||
1. **Navigeer naar uw werkmap**. Schakel in uw terminal naar de map (ook bekend als de directory) die u wilt beginnen met volgen. Typ:
|
||||
|
||||
```bash
|
||||
cd [naam van uw map]
|
||||
```
|
||||
|
||||
1. **Initialiseer een git-repository**. In uw project, typ:
|
||||
|
||||
```bash
|
||||
git init
|
||||
```
|
||||
|
||||
1. **Controleer de status**. Om de status van uw repository te controleren, typ:
|
||||
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
|
||||
de output kan er ongeveer zo uitzien:
|
||||
|
||||
```output
|
||||
Changes not staged for commit:
|
||||
(use "git add <file>..." to update what will be committed)
|
||||
(use "git checkout -- <file>..." to discard changes in working directory)
|
||||
|
||||
modified: file.txt
|
||||
modified: file2.txt
|
||||
```
|
||||
|
||||
Typisch vertelt een `git status` commando u dingen zoals welke bestanden klaar zijn om _opgeslagen_ te worden naar de repo of bevat veranderingen die u misschien wilt behouden.
|
||||
|
||||
1. **Voeg alle bestanden toe voor tracking**
|
||||
Dit wordt ook wel staging-bestanden/ bestanden toevoegen aan het staging-gebied genoemd.
|
||||
|
||||
```bash
|
||||
git add .
|
||||
```
|
||||
|
||||
Het `git add` plus `.` argument geeft aan dat al uw bestanden en wijzigingen voor tracking geselecteerd zijn.
|
||||
|
||||
1. **Voeg geselecteerde bestanden toe voor tracking**
|
||||
|
||||
```bash
|
||||
git add [bestands- of mapnaam]
|
||||
```
|
||||
|
||||
Dit helpt ons om alleen geselecteerde bestanden aan het staging-gebied toe te voegen als we niet alle bestanden tegelijk willen vastleggen.
|
||||
|
||||
1. **Unstage alle bestanden**
|
||||
|
||||
```bash
|
||||
git reset
|
||||
```
|
||||
|
||||
Dit commando helpt ons om alle bestanden tegelijk te unstagen.
|
||||
|
||||
1. **Unstage een bepaald bestand**
|
||||
|
||||
```bash
|
||||
git reset [bestands- of mapnaam]
|
||||
```
|
||||
|
||||
Dit commando helpt ons om alleen een bepaald bestand tegelijk te unstagen dat we niet willen opnemen voor de volgende commit.
|
||||
|
||||
1. **Uw werk voortzetten**. Op dit punt heeft u de bestanden toegevoegd aan een zogenaamd _staging-gebied_. Een plek waar Git uw bestanden bijhoudt. Om de wijziging permanent te maken, moet u de bestanden _commiten_. Om dit te doen maakt u een _commit_ aan met het `git commit` commando. Een _commit_ vertegenwoordigt een besparingspunt in de geschiedenis van uw repo. Typ het volgende om een _commit_ te maken:
|
||||
|
||||
```bash
|
||||
git commit -m "eerste commit"
|
||||
```
|
||||
|
||||
Dit commit al uw bestanden door het bericht "first commit" toe te voegen. Voor toekomstige commitberichten wilt u meer beschrijvend zijn in uw beschrijving om over te brengen wat voor soort wijziging u heeft aangebracht.
|
||||
|
||||
1. **Verbind uw lokale Git-repo met GitHub**. Een Git-repo is goed op uw computer, maar op een gegeven moment wilt u ergens een back-up van uw bestanden hebben en ook andere mensen uitnodigen om met u aan uw opslagplaats te werken. Een geweldige plek om dat te doen is GitHub. Onthoud dat we al een repo op GitHub hebben gemaakt, dus het enige dat we hoeven te doen, is onze lokale Git-repo verbinden met GitHub. Het commando `git remote add` zal precies dat doen. Typ de volgende commando:
|
||||
|
||||
> Let op: voordat u de opdracht typt, gaat u naar uw GitHub-repo-pagina om de repository-URL te vinden. U gebruikt het in het onderstaande commando. Vervang `repository_name` door uw GitHub-URL.
|
||||
|
||||
```bash
|
||||
git remote add origin https://github.com/username/repository_name.git
|
||||
```
|
||||
|
||||
Dit creëert een _remote_, of verbinding, genaamd "origin", wijzend naar de GitHub-repository die u eerder heeft gemaakt.
|
||||
|
||||
1. **Stuur lokale bestanden naar GitHub**. Tot nu toe heeft u een _verbinding_ gemaakt tussen de lokale repo en de GitHub-repo. Laten we deze bestanden naar GitHub sturen met het volgende commando `git push`, zoals zo:
|
||||
|
||||
```bash
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
Dit stuurt uw commits in uw "main" tak naar GitHub.
|
||||
|
||||
1. **Om meer wijzigingen toe te voegen**. Als u door wilt gaan met het aanbrengen van wijzigingen en ze naar GitHub wilt pushen, hoeft u alleen maar de volgende drie commando's te gebruiken:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "typ hier uw commitbericht"
|
||||
git push
|
||||
```
|
||||
|
||||
> Tip, misschien wilt u ook een `.gitignore`-bestand adopteren om te voorkomen dat bestanden die u niet wilt volgen, verschijnen op GitHub - zoals dat notitiesbestand dat u opslaat in dezelfde map maar geen plaats heeft op een openbare repository. U kunt sjablonen voor `.gitignore` bestanden vinden op [.gitignore templates](https://github.com/github/gitignore).
|
||||
|
||||
#### Commit berichten
|
||||
|
||||
Een geweldige onderwerpregel voor een commitbericht van Git maakt de volgende zin compleet:
|
||||
Indien toegepast, zal deze commit <uw onderwerpregel hier>
|
||||
|
||||
Gebruik voor het onderwerp de gebiedende wijs, tegenwoordige tijd: "verander" niet "veranderd" noch "veranderingen".
|
||||
Net als in het onderwerp, gebruik in het lichaam (optioneel) ook de imperatieve tegenwoordige tijd. Het lichaam moet de motivatie voor de verandering opnemen en dit contrasteren met eerder gedrag. U legt het `waarom` uit, niet het `hoe`.
|
||||
|
||||
✅ Neem een paar minuten de tijd om rond GitHub te surfen. Kunt u een echt geweldig commitbericht vinden? Kunt u een echt minimale vinden? Welke informatie is volgens u het belangrijkst en nuttigst om over te brengen in een commitbericht?
|
||||
|
||||
### Taak: Samenwerken
|
||||
|
||||
De belangrijkste reden om dingen op GitHub te zetten, was om het mogelijk te maken om samen te werken met andere ontwikkelaars.
|
||||
|
||||
## Samen met anderen aan projecten werken
|
||||
|
||||
Navigeer in uw repository naar `Insights > Community` om te zien hoe uw project zich verhoudt tot aanbevolen communitystandaarden.
|
||||
|
||||
Hier zijn enkele dingen die uw GitHub-repo kunnen verbeteren:
|
||||
- **Omschrijving**. Heeft u een beschrijving voor uw project toegevoegd?
|
||||
- **README**. Heeft u een README toegevoegd? GitHub biedt richtlijnen voor het schrijven van een [README](https://docs.github.com/articles/about-readmes/).
|
||||
- **Richtlijn voor bijdragen**. Heeft uw project [richtlijnen voor bijdragen](https://docs.github.com/articles/setting-guidelines-for-repository-contributors/),
|
||||
- **Gedragscode**. Een [Gedragscode](https://docs.github.com/articles/adding-a-code-of-conduct-to-your-project/),
|
||||
- **Licentie**. Misschien nog belangrijker, een [licentie](https://docs.github.com/articles/adding-a-license-to-a-repository/)?
|
||||
|
||||
|
||||
Al deze middelen zullen nieuwe teamleden helpen. En dat zijn typisch het soort dingen waar nieuwe bijdragers naar kijken voordat ze zelfs maar naar uw code kijken, om erachter te komen of uw project de juiste plek is om hun tijd door te brengen.
|
||||
|
||||
✅ README-bestanden, hoewel ze wat tijd nodig hebben om voor te bereiden, worden vaak genegeerd door drukke beheerders. Kunt u een voorbeeld vinden van een bijzonder beschrijvende? Opmerking: er zijn enkele [tools om goede README's te maken](https://www.makeareadme.com/) die u misschien zou willen proberen.
|
||||
|
||||
### Taak: voeg een code samen
|
||||
|
||||
Documenten voor bijdragen helpen mensen bij te dragen aan het project. Het legt uit wat voor soort bijdragen u zoekt en hoe het proces werkt. Bijdragers moeten een reeks stappen doorlopen om bij te dragen aan uw repo op GitHub:
|
||||
|
||||
|
||||
1. **Uw repo forken** Waarschijnlijk wilt u dat mensen uw project _forken_. Forken betekent het maken van een replica van uw repository op hun GitHub-profiel.
|
||||
1. **Kloon**. Van daaruit zullen ze het project naar hun lokale computer klonen (clone).
|
||||
1. **Maak een tak**. U zult ze willen vragen om een _tak_ voor hun werk te creëren (branch).
|
||||
1. **Richt hun verandering op één gebied**. Vraag bijdragers om hun bijdragen op één ding tegelijk te concentreren - op die manier is de kans groter dat u hun werk kan _samenvoegen_ (merge). Stelt u voor dat ze een bugfix schrijven, een nieuwe functie toevoegen en verschillende tests bijwerken - wat als u slechts 2 van de 3 of 1 van de 3 wijzigingen wilt of kunt implementeren?
|
||||
|
||||
✅ Stelt u een situatie voor waarin takken bijzonder cruciaal zijn voor het schrijven en verzenden van goede code. Welke use-cases kunt u bedenken?
|
||||
|
||||
> Let op: wees de verandering die u in de wereld wilt zien, en maak ook takken voor uw eigen werk. Alle commits die u maakt, worden gemaakt op de tak waar u momenteel naar "uitgecheckt" bent. Gebruik `git status` om te zien welke tak dat is.
|
||||
|
||||
Laten we een workflow voor bijdragers doorlopen. Veronderstel dat de bijdrager de repo al _geforkt_ en _gekloond_ heeft, zodat ze een Git-repo hebben klaar om aan te werken, op hun lokale computer:
|
||||
|
||||
1. **Maak een tak**. Gebruik het commando `git branch` om een branch te maken die de wijzigingen bevat die ze willen bijdragen:
|
||||
|
||||
```bash
|
||||
git branch [taknaam]
|
||||
```
|
||||
|
||||
1. **Overschakelen naar werkende tak**. Schakel over naar de gespecificeerde tak en update de werkdirectory met `git checkout`:
|
||||
|
||||
```bash
|
||||
git checkout [taknaam]
|
||||
```
|
||||
|
||||
1. **Werken**. Op dit punt wilt u uw wijzigingen toevoegen. Vergeet niet om Git erover te vertellen met de volgende commando's:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "mijn veranderingen"
|
||||
```
|
||||
|
||||
Zorg ervoor dat u uw commit een goede naam geeft, zowel voor u als voor de beheerder van de repo waarmee u helpt.
|
||||
|
||||
1. **Combineer uw werk met de `main` tak**. Op een gegeven moment bent u klaar met werken en wilt u uw werk combineren met dat van de `main` tak. De `main` tak kan ondertussen veranderd zijn, dus zorg ervoor dat u deze eerst bijwerkt naar de laatste versie met de volgende commando's:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull
|
||||
```
|
||||
|
||||
Op dit punt wilt u er zeker van zijn dat alle _conflicten_, situaties waarin Git niet gemakkelijk de veranderingen kan _combineren_ plaatsvinden in uw werkende tak. Voer daarom de volgende opdrachten uit:
|
||||
|
||||
```bash
|
||||
git checkout [taknaam]
|
||||
git merge main
|
||||
```
|
||||
|
||||
Dit brengt alle wijzigingen van `main` naar uw tak en hopelijk kunt u gewoon doorgaan. Als dit niet het geval is, zal VS Code u vertellen waar Git _in de war_ is en verandert u gewoon de betrokken bestanden om te zeggen welke inhoud het meest accuraat is.
|
||||
|
||||
1. **Stuur uw werk naar GitHub**. Het verzenden van uw werk naar GitHub betekent twee dingen. Uw tak naar uw repo pushen en vervolgens een PR, Pull Request openen.
|
||||
|
||||
```bash
|
||||
git push --set-upstream origin [taknaam]
|
||||
```
|
||||
|
||||
Het bovenstaande commando maakt de tak op uw geforkte repo.
|
||||
|
||||
1. **Open een PR**. Vervolgens wilt u een PR openen. U doet dat door naar de geforkte repo op GitHub te navigeren. U ziet een indicatie op GitHub waar het vraagt of u een nieuwe PR wilt maken, u klikt erop en u wordt naar een interface geleid waar u de titel van het commitbericht kunt wijzigen, geef het een meer geschikte beschrijving. Nu zal de beheerder van de repo die u heeft geforkt deze PR zien en, _vingers gekruist_, zullen ze uw PR waarderen en _samenvoegen_. U bent nu een bijdrager, yay :)
|
||||
|
||||
1. **Opruimen**. Het wordt als een goede gewoonte beschouwd om _op te ruimen_ nadat u met succes een PR hebt samengevoegd. U wilt zowel uw lokale tak opruimen als de tak die u naar GitHub hebt gepusht. Laten we het eerst lokaal verwijderen met het volgende commando:
|
||||
|
||||
```bash
|
||||
git branch -d [taknaam]
|
||||
```
|
||||
|
||||
Zorg ervoor dat u naar de GitHub-pagina gaat voor de geforkte repo en verwijder de externe tak die u er zojuist naartoe hebt gepusht.
|
||||
|
||||
`Pull request` lijkt een gekke term, omdat u uw wijzigingen echt in het project wilt pushen. Maar de onderhouder (projecteigenaar) of het kernteam moet rekening houden met uw wijzigingen voordat u deze samenvoegt met de "main" tak van het project, dus u vraagt echt om een wijzigingsbesluit van een onderhouder.
|
||||
|
||||
Een pull request is de plek om de verschillen die op een tak zijn geïntroduceerd te vergelijken en te bespreken met recensies, opmerkingen, geïntegreerde tests en meer. Een goed pull request volgt ongeveer dezelfde regels als een commitbericht. U kunt een verwijzing naar een probleem (issue) toevoegen in de issue tracker, bijvoorbeeld wanneer uw werk een probleem oplost. Dit doet u met een `#` gevolgd door het nummer van uw probleem. Bijvoorbeeld `# 97`.
|
||||
|
||||
🤞Duimen dat alle controles slagen en de projecteigenaar(s) uw wijzigingen in het project samenvoegen🤞
|
||||
|
||||
Update uw huidige lokale werkende tak met alle nieuwe commits van de corresponderende remote tak op GitHub:
|
||||
|
||||
`git pull`
|
||||
|
||||
## Hoe u kunt bijdragen aan open source
|
||||
|
||||
Laten we eerst een repository - of: repo - op GitHub zoeken die voor u interessant is en waaraan u een wijziging zou willen bijdragen. U zult de inhoud ervan naar uw machine kopiëren.
|
||||
|
||||
✅ Een goede manier om 'beginnersvriendelijke' repos te vinden, is door [te zoeken op de tag 'good-first-issue'](https://github.blog/2020-01-22-browse-good-first-issues-to-start-contributing-to-open-source/).
|
||||
|
||||
|
||||
|
||||
Er zijn verschillende manieren om code te kopiëren. Een manier is om de inhoud van de repository te "klonen" door HTTPS, SSH of de GitHub CLI (Command Line Interface) te gebruiken.
|
||||
|
||||
Open uw terminal en kloon de repository op deze manier:
|
||||
`git clone https://github.com/ProjectURL`
|
||||
|
||||
Schakel naar de juiste map om aan het project te werken:
|
||||
`cd ProjectURL`
|
||||
|
||||
U kunt ook het hele project openen met [Codespaces](https://github.com/features/codespaces), GitHub's ingesloten code-editor /cloud-ontwikkelomgeving of [GitHub Desktop](https://desktop.github.com/).
|
||||
|
||||
Ten slotte kunt u de code downloaden in een gecomprimeerde map.
|
||||
|
||||
### Nog een paar interessante dingen over GitHub
|
||||
|
||||
U kunt elke openbare repository op GitHub een ster geven, bekijken en/of "forken". U kunt uw repositories met ster vinden in het vervolgkeuzemenu rechtsboven. Het is net als bladwijzers, maar dan voor code.
|
||||
|
||||
Projecten hebben een issue tracker, meestal op GitHub in de "Issues" tab, tenzij anders aangegeven, waar mensen problemen bespreken die verband houden met het project. En op het tabblad Pull Requests bespreken en beoordelen mensen lopende wijzigingen.
|
||||
|
||||
Projecten kunnen ook worden besproken in forums, mailinglijsten of chatkanalen zoals Slack, Discord of IRC.
|
||||
|
||||
✅ Kijk eens rond in uw nieuwe GitHub-repo en probeer een paar dingen, zoals het bewerken van instellingen, het toevoegen van informatie aan uw repo en het maken van een project (zoals een Kanban-bord). U kunt veel doen!
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Uitdaging
|
||||
|
||||
Koppel met een vriend om aan elkaars code te werken. Creëer gezamenlijk een project, fork code, maak takken en voeg wijzigingen samen.
|
||||
|
||||
## Quiz na de lezing
|
||||
[Quiz na de lezing](https://nice-beach-0fe9e9d0f.azurestaticapps.net/quiz/4)
|
||||
|
||||
## Beoordeling en zelfstudie
|
||||
|
||||
Lees meer over [bijdragen aan open source software](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution).
|
||||
|
||||
[Git-cheatsheet](https://training.github.com/downloads/github-git-cheat-sheet/).
|
||||
|
||||
Oefenen, oefenen, oefenen. GitHub heeft geweldige leertrajecten beschikbaar via [lab.github.com](https://lab.github.com/):
|
||||
|
||||
- [Eerste week op GitHub](https://lab.github.com/githubtraining/first-week-on-github)
|
||||
|
||||
U zult ook meer geavanceerde labs vinden.
|
||||
|
||||
## Toewijzing
|
||||
|
||||
Voltooi [de eerste week op GitHub-trainingslaboratorium](https://lab.github.com/githubtraining/first-week-on-github)
|
||||
@@ -0,0 +1,318 @@
|
||||
# GitHub 介绍
|
||||
|
||||
这节课涵盖了 GitHub 的基础知识，这是一个可以用来存放代码和管理代码变更的平台。
|
||||
|
||||
|
||||
> 涂鸦笔记作者：[Tomomi Imura](https://twitter.com/girlie_mac)
|
||||
|
||||
## 课前小测
|
||||
[课前小测](https://nice-beach-0fe9e9d0f.azurestaticapps.net/quiz/3?loc=zh_cn)
|
||||
|
||||
## 大纲
|
||||
|
||||
这节课我们将会介绍：
|
||||
|
||||
- 在你的电脑上追踪你的工作
|
||||
- 与他人协同开发项目
|
||||
- 如何参与开源软件贡献
|
||||
|
||||
### 开始之前
|
||||
|
||||
开始之前，你需要确保安装了 Git，在终端（译注：即上一节课中介绍的命令行）中输入：
|
||||
`git --version`
|
||||
|
||||
如果没有安装 Git，请先[下载并安装 Git](https://git-scm.com/downloads)。然后用如下命令设置你的本地 Git 使用者配置文件：
|
||||
* `git config --global user.name "your-name"`
|
||||
* `git config --global user.email "your-email"`
|
||||
|
||||
要检查 Git 使用者是否配置完成，可以输入：
|
||||
`git config --list`
|
||||
|
||||
你还需要一个 GitHub 账户，一个代码编辑器（比如 Visual Studio Code），并且要打开你的终端（或者其他命令行）。
|
||||
|
||||
如果你没有现成的 Github 账号，去 [github.com](https://github.com/) 创建一个。如果已经有账号，就登录进去并且完成个人资料的配置。
|
||||
|
||||
✅ GitHub 并不是世界上唯一的代码仓库，但是最知名的。
|
||||
|
||||
### 课前准备
|
||||
|
||||
你需要在本地（你的笔记本或 PC）创建一个项目文件夹，还需要在 GitHub 上创建一个公开的仓库（译注：后文会有指引），作为本节课中向其他人的项目提贡献的示例。
|
||||
|
||||
---
|
||||
|
||||
## 代码管理
|
||||
|
||||
假如你在本地有一个代码项目的文件夹，你希望开始使用 Git （版本控制系统）来追踪你的进度。有的人将使用 Git 比作给未来的你自己写一封情书，在数日、数周乃至数月后阅读你的提交信息（commit messages）时，你就可以想起你做出某个决定的原因，或者回滚（rollback）一次变更 —— 前提是你写了不错的提交信息。
|
||||
|
||||
### 任务：创建仓库并提交代码
|
||||
|
||||
1. **在 GitHub 上创建仓库**。进入 GitHub.com，在 “Repositories” 标签或者右上角导航栏找到 **New repository** 按钮。
|
||||
|
||||
1. 给你的仓库取个名字；
|
||||
1. 点击 **Create repository**。
|
||||
|
||||
1. **前往你的工作目录**。在你的终端中，通过输入下方命令切换到你希望开始追踪的文件夹（即目录）：
|
||||
|
||||
```bash
|
||||
cd [文件名称/目录路径]
|
||||
```
|
||||
|
||||
1. **初始化一个 Git 仓库**。在你的项目下输入：
|
||||
|
||||
```bash
|
||||
git init
|
||||
```
|
||||
|
||||
1. **检查状态**。要检查你的仓库状态，输入：
|
||||
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
|
||||
输出看起来将会像这样：
|
||||
|
||||
```output
|
||||
Changes not staged for commit:
|
||||
(use "git add <file>..." to update what will be committed)
|
||||
(use "git checkout -- <file>..." to discard changes in working directory)
|
||||
|
||||
modified: file.txt
|
||||
modified: file2.txt
|
||||
```
|
||||
|
||||
一般来说 `git status` 命令会告诉你诸如什么文件已经 _被保存到_ 仓库内或者有一些你可能想要保留的变更之类的事。
|
||||
|
||||
1. **追踪所有文件**
|
||||
这个操作也叫做暂存（stage）文件或者将文件添加到暂存区（staging area）。
|
||||
|
||||
```bash
|
||||
git add .
|
||||
```
|
||||
|
||||
`git add` 命令加上 `.` 参数将会追踪你的所有文件和变更。
|
||||
|
||||
1. **只追踪选定的文件**
|
||||
|
||||
```bash
|
||||
git add [文件或文件夹名]
|
||||
```
|
||||
|
||||
如果你不想一次性将所有文件添加到暂存区，可以用这个命令仅仅添加选定的文件。
|
||||
|
||||
1. **取消所有文件的追踪**
|
||||
|
||||
```bash
|
||||
git reset
|
||||
```
|
||||
|
||||
这条命令可以帮我们取消暂存（unstage）所有文件。
|
||||
|
||||
1. **取消特定文件的追踪**
|
||||
|
||||
```bash
|
||||
git reset [文件或文件夹名]
|
||||
```
|
||||
|
||||
如果你在下次提交中不希望提交某个已经暂存的文件，可以用这条命令取消它的暂存。
|
||||
|
||||
1. **保存你的工作**。现在你应该已经将文件添加到了所谓 _暂存区_ 中，这是 Git 追踪你的文件的地方。为了永久地保存变更，你需要 _提交（commit）_ 这些文件。你可以用 `git commit` 命令创建一次 _提交_。一次 _提交_ 代表你的仓库历史中的一个存档点。输入下方命令来创建一次 _提交_：
|
||||
|
||||
```bash
|
||||
git commit -m "first commit"
|
||||
```
|
||||
|
||||
这会提交你暂存区中的所有文件，并带上一条提交信息 —— “first commit”。在以后的提交信息中你会想要加入更加准确的描述，比如一些表示你这次变更的类型的信息。
|
||||
|
||||
1. **将你的本地仓库连接到 GitHub**。现在 Git 仓库已经能在你的本地机器上正常运作，但是有时候你会想要将你的文件备份到别处，或者希望邀请其他人来一起参与这个仓库的协作。GitHub 就是一个可以满足你要求的好地方。我们此前已经在 GitHub 上创建了一个仓库，现在只需要将本地 Git 仓库连接到 GitHub 就可以了，用 `git remote add` 命令就可以做到。输入下面的命令：
|
||||
|
||||
> 注意，在你输入命令前，需要前往你的 GitHub 仓库而页面来找到仓库的地址（URL），用它来替换命令中 `username/repository_name` 这一部分。
|
||||
|
||||
```bash
|
||||
git remote add origin https://github.com/username/repository_name.git
|
||||
```
|
||||
|
||||
这会创建一个被命名为 “origin” 的 _远程仓库位置（remote）_，也可以理解为一个连接，指向你早先创建的 GitHub 仓库。
|
||||
|
||||
1. **将本地文件上传至 GitHub**。现在你已经创建了一个本地仓库和 GitHub 仓库间的 _连接_。让我们通过 `git push` 命令将这些文件上传至 GitHub，就像这样：
|
||||
|
||||
```bash
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
这样就会把你的提交上传到 GitHub 上你的 “main” 分支了。
|
||||
|
||||
1. **添加更多的变更**。如果你想继续搞点变更并且将它们传到 GitHub 上，你只需要使用下面的三行命令：
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "在这里填写你的提交信息"
|
||||
git push
|
||||
```
|
||||
|
||||
> 提示，你可能还需要建立一个 `.gitignore` 文件来防止 Git 追踪一些文件并且让它们不会被上传到 GitHub，比如一些你写在本地仓库但并不想放到公开仓库的笔记文件。你可以在 [.gitignore templates](https://github.com/github/gitignore) 找到一些现成的 `.gitignore` 文件模板。
|
||||
|
||||
#### 提交信息（Commit Messages）
|
||||
|
||||
一条好的 Git 提交信息标题（subject line）可以理解为下方句子的填空：
|
||||
如果生效，这次提交将会 <你的提交信息标题>
|
||||
|
||||
在标题内，使用祈使语气和现在时态，即使用 “change” 而非 “changed” 或 “changes”。
|
||||
同理，在正文（body，可选）中也要用祈使语气和现在时态。正文中需要包括更改的动机，并对比与更改前后行为的变化。确保你说明的是`为什么`，而不是`怎么做`。
|
||||
|
||||
✅ 花几分钟逛逛 GitHub。你能找到感觉非常棒的提交信息吗？你可以找到非常简洁的提交信息吗？你认为在一条提交信息中，传达什么信息是最重要和有用的？
|
||||
|
||||
### 任务：协作
|
||||
|
||||
将项目放到 GitHub 的主要原因是让和其他开发者协作开发成为可能。
|
||||
|
||||
## 和其他人协作开发项目
|
||||
|
||||
在你的仓库中，前往 `Insights > Community` 来查看你的项目和推荐的社区规范的对比。
|
||||
|
||||
这里有一些你可以改进你的项目仓库的点：
|
||||
- **项目描述（Description）**。你为你的项目添加了描述吗？
|
||||
- **README**。你有添加 README 吗？GitHub 提供了撰写 [README](https://docs.github.com/articles/about-readmes/) 的指南。
|
||||
- **贡献指南（Contributing guideline）**。你的项目是否有[贡献指南](https://docs.github.com/articles/setting-guidelines-for-repository-contributors/)？
|
||||
- **行为准则（Code of Conduct）**。添加一份 [行为准则](https://docs.github.com/articles/adding-a-code-of-conduct-to-your-project/)
|
||||
- **开源协议（License）**。或许是最重要的，添加一个[开源协议](https://docs.github.com/articles/adding-a-license-to-a-repository/)
|
||||
|
||||
|
||||
所有这些资源对于新加入的团队成员都是很有好处的，这些一般是新的贡献者在看你的代码前会更先去看的东西，以确认你的项目是否值得他们在这上面花费时间。
|
||||
|
||||
✅ 尽管很多人都准备了 README 文件，但常常会因为太忙而疏于维护。你能找到一个这样的例子吗？注：这里有一些可以[用于创建优秀的 README 的工具](https://www.makeareadme.com/)，你或许愿意试试。
|
||||
|
||||
### 任务：合并（Merge）一些代码
|
||||
|
||||
贡献文档帮助人们对项目做贡献，其中说明了你正需要什么样的贡献以及贡献的过程该是怎样的。贡献者需要完成一系列步骤才能在 GitHub 上参与你项目的贡献：
|
||||
|
||||
|
||||
1. **复刻（Fork）你的仓库**。你可能希望人们 _复刻_ 你的项目。复刻意味着在他们自己的 GitHub 账户下创建你的项目的一份副本。
|
||||
1. **克隆（Clone）**。在这里他们将会将项目克隆到他们的本地机器上。
|
||||
1. **创建一个分支（Branch）**。你可能希望他们能创建一个 _分支_ 来进行他们的工作。
|
||||
1. **集中进行一个区域的修改**。要求贡献者每次贡献只专注做一件事，这样你才更可能 _合并_ 他们的工作。想象一下如果他们修了一个 BUG，添加了一个新特性，然后更新了几个测试，而你其实只想要其中的一个或两个更改时该怎么办？
|
||||
|
||||
✅ 想一想分支在什么情况下对于编写和发布优质的代码非常重要？你能想到哪些使用实例？
|
||||
|
||||
> 注意，要以身作则，对你自己的工作也要创建分支。任何提交都需要在当前“检出（checked out）”的分支上进行。使用 `git status` 来查看是哪一个分支。
|
||||
|
||||
让我们走一遍贡献者的工作流程。假设贡献者已经 _复刻_ 并 _克隆_ 了仓库，他们在本地机器已经有了一个可以工作的仓库：
|
||||
|
||||
1. **创建一个分支**。使用命令 `git branch` 来创建一个他们希望用来包含计划进行的变更的分支：
|
||||
|
||||
```bash
|
||||
git branch [分支名]
|
||||
```
|
||||
|
||||
1. **切换到工作分支**。使用 `git checkout` 来切换到指定分支并且更新工作目录中的文件：
|
||||
|
||||
```bash
|
||||
git checkout [分支名]
|
||||
```
|
||||
|
||||
1. **干活**。现在你可以添加你的变更了，别忘了用下面的命令告诉 Git 你所做的工作：
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "变更内容"
|
||||
```
|
||||
|
||||
确保你的提交有一个好名字，不论是对你自己还是你正在帮助的仓库维护者来说都有好处。
|
||||
|
||||
1. **将你的工作合入 `main` 分支**。在完成工作后，你打算将你的工作和 `main` 分支上的合并。`main` 分支可能同时有了一些新的变更，所以要先用以下命令确保将其更新至最新版本：
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull
|
||||
```
|
||||
|
||||
这时你想确认是否存在 _冲突（conflicts）_，即 Git 没法简单地将这些变化 _合入_ 你的分支的情况。为此运行下面的命令：
|
||||
|
||||
```bash
|
||||
git checkout [分支名]
|
||||
git merge main
|
||||
```
|
||||
|
||||
这将会把所有 `main` 分支上的变更带入到你的分支上。运气好的话一切都会自动搞定，否则 VS Code 会告诉你哪些文件 Git _不确定_ 该如何合并，你只需要手动修改对应文件来解决冲突即可。
|
||||
|
||||
1. **将你的工作上传至 GitHub**。将你的工作上传至 GitHub 意味着两件事：把你的分支上传到你自己的仓库，然后开启一个 PR（Pull Request）：
|
||||
|
||||
```bash
|
||||
git push --set-upstream origin [分支名]
|
||||
```
|
||||
|
||||
上述命令在你复刻的仓库中创建了一个分支。
|
||||
|
||||
1. **开启一个 PR**。接下来，你打算开启一个 PR。前往 GitHub 上你打算贡献的仓库，你将会看到一个消息条询问你是否想要创建一个新的 PR，点击后即可进入创建 PR 的界面。在这里你可以更改提交标题，给出更准确的描述。创建 PR 后，仓库维护者将会看到这个，如果 _一切顺利_ 的话他们会表示感谢并且 _合并_ 你的 PR。你现在就是一位贡献者啦！ :)
|
||||
|
||||
1. **清理**。成功合入一个 PR 后，做做 _清理_ 是一个好习惯。你会想要清理本地和你上传到 GitHub 的分支。首先让我们通过下面的命令来删除本地的分支：
|
||||
|
||||
```bash
|
||||
git branch -d [分支名]
|
||||
```
|
||||
|
||||
接下来请确保前往 GitHub 中对应仓库的页面并删除你刚才上传的分支。
|
||||
|
||||
`Pull request` 这个术语看起来有些憨，因为你确实打算把你的变更提交到这个项目中。但是在将你的变更合入到项目的 `main` 分支前，维护者（项目拥有者）或者核心团队需要考虑和检查你的变更，这意味着你实际上是在请求（request）维护者的变更决定。
|
||||
|
||||
Pull Request 是一个可以用来比较和讨论一个分支引入的改动的地方，并有代码审查、评论、集成测试等功能。优质的 Pull Request 严格遵照与提交信息相同的规则。如果你的工作是为了修复一个 Issues 面板中的事项，你可以在 PR 中提及这个事项。具体做法是写一个 `#` 加上事项的编号，比如 `#97`。
|
||||
|
||||
🤞如果一切顺利，所有的检查都通过后项目拥有者就会将你的变更合入项目🤞
|
||||
|
||||
使用这个命令即可将 GitHub 上对应远程分支的所有新提交更新到当前本地的工作分支上：
|
||||
|
||||
`git pull`
|
||||
|
||||
## 如何参与开源贡献
|
||||
|
||||
首先，让我们在 GitHub 上找到一个你感兴趣且愿意参与贡献的仓库（**repo**），你会复制一份它的内容到你的机器上。
|
||||
|
||||
✅ 一个寻找对入门者友好的仓库的好办法是[搜索 “good-first-issue” 标签](https://github.blog/2020-01-22-browse-good-first-issues-to-start-contributing-to-open-source/)。
|
||||
|
||||
|
||||
|
||||
有很多种复制代码的方法，其中一种就是“克隆”仓库的内容，可以用 HTTPS、SSH 或者 GitHub CLI（Command Line Interface）来做到。
|
||||
|
||||
打开你的终端并且用类似下方的命令来克隆仓库：
|
||||
`git clone https://github.com/ProjectURL`
|
||||
|
||||
切换到正确的工作目录：
|
||||
`cd ProjectURL`
|
||||
|
||||
你也可以用 [Codespaces](https://github.com/features/codespaces) 来打开整个项目，这是 GitHub 内置的代码编辑器和云开发环境，或者用 [GitHub Desktop](https://desktop.github.com/)。
|
||||
|
||||
当然，你也可以直接下载代码的压缩包。
|
||||
|
||||
### 更多 GitHub 的有趣小知识
|
||||
|
||||
你可以收藏（star）、关注（watch）和/或复刻（fork）GitHub 上的任何公开仓库。可以在右上角的下拉菜单找到你收藏的仓库，这就像书签一样，但收藏的是代码。
|
||||
|
||||
项目都有一个事项面板（issue tracker），用于让人们讨论和这个项目相关的事项，事项面板基本都在 GitHub 的 “Issues” 标签页中，偶尔也会指明在其他地方。而 “Pull Requests” 标签页则是人们讨论和检查正在进行的变更的地方。
|
||||
|
||||
项目也可能会在论坛、邮件列表或者如 Slack、Discord、IRC 这样的聊天频道进行讨论。
|
||||
|
||||
✅ 看看你新建立的 GitHub 仓库，尝试做一些其他事，比如编辑设置、为仓库增加信息、创建一个 Project（类似看板），有很多可以尝试的东西！
|
||||
|
||||
---
|
||||
|
||||
## 🚀 挑战
|
||||
|
||||
找朋友一起编辑彼此的代码。协作创建一个项目、复刻代码、创建分支，然后合并变更。
|
||||
|
||||
## 课后小测
|
||||
[课后小测](https://nice-beach-0fe9e9d0f.azurestaticapps.net/quiz/4?loc=zh_cn)
|
||||
|
||||
## 复习 & 自学
|
||||
|
||||
了解更多 [如何提交贡献](https://opensource.guide/zh-hans/how-to-contribute/#%E5%A6%82%E4%BD%95%E6%8F%90%E4%BA%A4%E8%B4%A1%E7%8C%AE)。
|
||||
|
||||
[Git cheatsheet](https://training.github.com/downloads/github-git-cheat-sheet/)。
|
||||
|
||||
练习，练习，再练习。GitHub 在 [lab.github.com](https://lab.github.com/) 提供了很棒的学习路径：
|
||||
|
||||
- [在 GitHub 的第一周](https://lab.github.com/githubtraining/first-week-on-github)
|
||||
|
||||
你还可以在上面找到更多高阶的实验内容。
|
||||
|
||||
## 作业
|
||||
|
||||
完成 [在 GitHub 的第一周](https://lab.github.com/githubtraining/first-week-on-github)
|
||||
@@ -0,0 +1,319 @@
|
||||
# GitHub 簡介
|
||||
|
||||
這堂課程講述一個提供加設與管理程式碼的平台 ── Github的基本功能。
|
||||
|
||||
|
||||
> 由[Tomomi Imura](https://twitter.com/girlie_mac) 繪製
|
||||
|
||||
## 課前測驗
|
||||
[課前測驗](https://nice-beach-0fe9e9d0f.azurestaticapps.net/quiz/3?loc=zh_tw)
|
||||
|
||||
## 大綱
|
||||
|
||||
在這堂課中，包含：
|
||||
|
||||
- 追蹤裝置上的工作專案
|
||||
- 與其他人共同開發專案
|
||||
- 如何貢獻網路上的開源軟體
|
||||
|
||||
### 開始之前
|
||||
|
||||
在你開始課程之前，你需要安裝 Git 這套套件。在你的終端機上輸入：
|
||||
`git --version`
|
||||
|
||||
若你的裝置上沒有安裝 Git，[請下載並安裝 Git](https://git-scm.com/downloads)。 安裝完之後，請設定裝置本地 Git 的使用者設定。
|
||||
* `git config --global user.name "your-name"`
|
||||
* `git config --global user.email "your-email"`
|
||||
|
||||
要確認 Git 使用者設定是否完成，你可以輸入：
|
||||
`git config --list`
|
||||
|
||||
此外，你需要一組 GitHub 的帳戶、一款文字編輯器 (如：Visual Studio Code) 與你的終端機 (或 command prompt)。
|
||||
|
||||
若你缺少 GitHub 帳戶，請前往 [github.com](https://github.com/)建立並登入一組帳戶，遵循指示完成資料的填寫。
|
||||
|
||||
✅ GitHub 不是唯一的程式碼數據庫，但 GitHub 是家喻戶曉的。
|
||||
|
||||
### 課前準備
|
||||
|
||||
你需要在裝置(筆電或電腦)上建立程式專案的資料夾，與 GitHub 公共的數據庫(Public Repository)。之後的例子會使用到此公共數據庫來與他人分享程式碼。
|
||||
|
||||
---
|
||||
|
||||
## 程式碼管理
|
||||
|
||||
假設你的本地端資料夾存放著一些程式專案，你想利用 Git 來作專案追蹤與版本控制，甚至是對未來的你寫一封情書。在一天、一週甚至是一個月後閱讀你的提交紀錄，了解當初你的決定，回想之前的更動。前提是當初你有寫一條完整的提交紀錄。
|
||||
|
||||
### 課題：建立數據庫並提交程式碼
|
||||
|
||||
1. **在 GitHub 上建立數據庫** 在 GitHub.com 上，在 "Repositories" 的標籤或導航欄的右上方，找到 **new repo** 的按鈕。
|
||||
|
||||
1. 為你的數據庫資料夾取個名字。
|
||||
1. 選擇 **建立數據庫(create repository)**.
|
||||
|
||||
1. **調查本地的專案資料夾** 在終端機中開啟儲存程式碼的資料夾，在你想追蹤的目錄下輸入：
|
||||
|
||||
```bash
|
||||
cd [資料夾名稱]
|
||||
```
|
||||
|
||||
1. **初始化 git 數據庫(repo)** 在目錄下輸入：
|
||||
|
||||
```bash
|
||||
git init
|
||||
```
|
||||
|
||||
1. **檢查狀態** 若想檢查目前數據庫的狀態，輸入：
|
||||
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
|
||||
它會輸出類似以下的訊息：
|
||||
|
||||
```output
|
||||
Changes not staged for commit:
|
||||
(use "git add <file>..." to update what will be committed)
|
||||
(use "git checkout -- <file>..." to discard changes in working directory)
|
||||
|
||||
modified: file.txt
|
||||
modified: file2.txt
|
||||
```
|
||||
|
||||
指令 `git status` 會回報那些檔案已經準備 _被存到_ 數據庫或是被更動過但不想更新上去。
|
||||
|
||||
1. **開始追蹤所有檔案**
|
||||
新增檔案到暫存區(staging area)。
|
||||
|
||||
```bash
|
||||
git add .
|
||||
```
|
||||
|
||||
`git add` 加上路徑 `.` 表示追蹤該路徑下所有的檔案。
|
||||
|
||||
1. **只追蹤選擇的檔案**
|
||||
|
||||
```bash
|
||||
git add [檔案或資料夾路徑]
|
||||
```
|
||||
|
||||
上述指令幫助你只追蹤被選取的檔案，允許使用者分批提交。
|
||||
|
||||
1. **取消追蹤所有檔案**
|
||||
|
||||
```bash
|
||||
git reset
|
||||
```
|
||||
|
||||
上述指令能取消追蹤(unstage)暫存區的檔案。
|
||||
|
||||
1. **取消追蹤特定的檔案**
|
||||
|
||||
```bash
|
||||
git reset [檔案或資料夾路徑]
|
||||
```
|
||||
|
||||
上述指令只取消追蹤單一檔案，在下一次提交時不被圈選在裡面。
|
||||
|
||||
1. **保存工作狀態** 現在，已經有一些檔案被標記在 _暫存區(staging area)_。 Git 會追蹤區域內的檔案。若要保存這些檔案的狀態，你需要 _提交(commit)_ 這些檔案。 _提交_ 會記錄當下數據庫中檔案的狀態到歷史紀錄中。 你需要指令`git commit` 完成這項工作。
|
||||
|
||||
```bash
|
||||
git commit -m "first commit"
|
||||
```
|
||||
|
||||
這會提交暫存區內的檔案，"first commit"即提交紀錄。提交紀錄最好能識別出這次的提交主要做了那些更動。
|
||||
|
||||
1. **連接本地數據庫到 GitHub 遠端數據庫** 現在 Git 數據庫已經成功運行在你的本地裝置上，但有時候你希望能將檔案備份到其他地方，或是邀請他人參與這項程式專案。 GitHub 便是一個好地方。先前我們已經建立遠端數據庫在 GitHub 上，現在我們只要連接本地數據庫到 GitHub上。指令 `git remote add` 能完成這項課題：
|
||||
|
||||
> 注意，在輸入指令前，你需要取得 GitHub 遠端數據庫的 URL 位置。請將下列的 `repository_name` 替換為你的遠端數據庫路徑。
|
||||
|
||||
```bash
|
||||
git remote add origin https://github.com/username/repository_name.git
|
||||
```
|
||||
|
||||
這會在 GitHub 遠端數據庫上建立一個名叫 "origin" 的 _遠端位置(remote)_ ，或稱 _連接(connection)_。
|
||||
|
||||
1. **上傳本地檔案到 GitHub** 現在已經建好了遠端與本地的 _連接_。 利用指令 `git push` 可以將本地檔案上傳到遠端數據庫當中：
|
||||
|
||||
```bash
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
所有的提交都會加到 GitHub 上 "main" 的分支當中。
|
||||
|
||||
1. **增加更多的更動** 若之後再對程式碼有所更動、提交並上傳到 GitHub 上，只要輸入：
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "type your commit message here"
|
||||
git push
|
||||
```
|
||||
|
||||
> 提示：建立 `.gitignore` 檔案可以讓你自動排除的特定檔案項目不被 GitHub 追蹤。好比是有一個在同一個目錄下的筆記檔不想被上傳到遠端數據庫。以下是 `.gitignore` 的參考版型： [.gitignore 參考版型](https://github.com/github/gitignore)。
|
||||
|
||||
#### 提交紀錄(Commit Messages)
|
||||
|
||||
一條好的 Git 提交標題行最好滿足下列條件：
|
||||
提交完後，提交紀錄會顯示 <你的標題>
|
||||
|
||||
標題使用祈使語句，如使用 "change" 而非 "changed" 或 "changes"。
|
||||
同理地，內文(選擇性)也使用祈使語句。內文須包含改動的動機與改動前後的差異。你需要解釋「為什麼改」而非「怎麼改」。
|
||||
|
||||
✅ 花點時間在 GitHub 上閒晃。你能找到很棒的提交紀錄嗎? 你能找到簡潔的提交紀錄嗎? 哪些資訊是你認為一個提交紀錄要有的重要資訊?
|
||||
|
||||
### 課題：多人合作
|
||||
|
||||
另一個將專案上傳到 GitHub 的主要原因是讓其他開發者能參與其中。
|
||||
|
||||
## 與其他人共同開發專案
|
||||
|
||||
在你的遠端資料庫中，前往 `Insights > Community` 來對比你的專案與其他推薦社群專案。
|
||||
|
||||
以下是一些你的 GitHub 數據庫需要精進的地方：
|
||||
- **專案描述(Description)** 你有為你的專案新增描述嗎?
|
||||
- **README** 你有新增 README 嗎? GitHub 提供編寫 README 的指引與參考： [README](https://docs.github.com/articles/about-readmes/)
|
||||
- **開發指引(Contributing guideline)** 你的專案內有[開發指引](https://docs.github.com/articles/setting-guidelines-for-repository-contributors/)嗎?
|
||||
- **行為準則(Code of Conduct)** [行為準則](https://docs.github.com/articles/adding-a-code-of-conduct-to-your-project/)
|
||||
- **授權條款License** 這或許是最重要的：[授權條款](https://docs.github.com/articles/adding-a-license-to-a-repository/)
|
||||
|
||||
|
||||
這些資源對剛加入到專案的新成員有所幫助。這些是新的合作夥伴比看程式碼還優先查詢的地方。完善它們能有效縮減他人消化的時間。
|
||||
|
||||
✅ README 檔，雖然多數人都會配置，但忙碌的開發者都會疏於管理。 你能在社群中找到相關的例子嗎? 這邊有[關於建立 READMEs 的有利工具](https://www.makeareadme.com/)可以嘗試。
|
||||
|
||||
### 課題：合併程式碼
|
||||
|
||||
開發指引文件幫助他人了解如何共同開發專案。它提供專案需要被貢獻的部分與該如何運作。共同開發者需要經過下列步驟來與他人在 GitHub 共同開發專案：
|
||||
|
||||
1. **分叉(Fork)專案** 你或許希望別人能 _分叉(fork)_ 你的專案。 分叉代表別人建立一份你的專案副本到他人的 GitHub 數據庫中。
|
||||
1. **複製(Clone)** 複製專案到他人的本地裝置中。
|
||||
1. **建立分支(branch)** 依照工作需求建立 _分支(branch)_。
|
||||
1. **專注在他人投入的工作範圍** 要求他人只專注在單一課題上，這樣能提升他們工作 _合併(merge)_ 的機會。想像他們在修正錯誤，同時又新增新功能、更新測試機制......這時如果你只想合併其中的一個、或者是兩個功能呢?
|
||||
|
||||
✅ 想像一個情況：一個重要的分支是編輯與分享的主軸，它能被如何應用?
|
||||
|
||||
> 注意，在做更動前，記得建立新的分支。任何提交都會在你所在的分支上，指令 `git status` 可以檢查你現在所在的分支。
|
||||
|
||||
現在，我們以共同開發者的角度來看。假設開發者已經 _分支_ 且 _複製_ 了他人的數據庫到自己的 Git 數據庫上，準備開始編輯檔案：
|
||||
|
||||
1. **建立新的分支** 利用指令 `git branch` 來建立新的分支，只做相關的工作改動。
|
||||
|
||||
```bash
|
||||
git branch [分支名稱]
|
||||
```
|
||||
|
||||
1. **切換到該工作分支** 使用指令 `git checkout` 來切換到特定分支，更新分支的檔案狀態：
|
||||
|
||||
```bash
|
||||
git checkout [分支名稱]
|
||||
```
|
||||
|
||||
1. **程式設計** 記得追蹤你所更改的地方，利用下列的指令來告訴 Git：
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "my changes"
|
||||
```
|
||||
|
||||
請確保提交都有適當的名稱，對管理者與你自己都有好處。
|
||||
|
||||
1. **將工作分支與 `main` 分支進行合併** 當工作完成時，你會需要將工作分支與 `main` 分支進行合併。 `main` 分支可能會被他人更新，在合併之前記得更新主分支：
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull
|
||||
```
|
||||
|
||||
這項步驟可能會面臨到 _衝突(conflicts)_，代表 Git 無法將本地的更動作 _合併(combine)_ 。此時你需要執行下列的指令：
|
||||
|
||||
```bash
|
||||
git checkout [分支名稱]
|
||||
git merge main
|
||||
```
|
||||
|
||||
這會將所有 `main` 分支的改動加入到你的本地目錄中。若出現狀況，VS Code會告訴你 Git 會對衝突的檔案感到 _困惑(confused)_， 你需要判斷哪一項檔案或程式碼才是最適當的選擇。
|
||||
|
||||
1. **將你的成果上傳到 GitHub** 這代表著兩件事：將分支推到你的遠端數據庫以及準備建立 Pull Request(PR)。
|
||||
|
||||
```bash
|
||||
git push --set-upstream origin [分支名稱]
|
||||
```
|
||||
|
||||
上述的指令會在分叉的數據庫中新增分支。
|
||||
|
||||
1. **建立 PR** 藉由造訪分叉的數據庫中建立 PR，GitHub 會指示你是否要建立 PR，之後要填寫提交紀錄以及編寫詳細的說明。讓管理者了解你做了哪些更動並進行 _交叉比對(fingers crossed)_。 他們會感激你的貢獻並 _合併(merge)_ 你的 PR。完成這步後，你就成為了專案貢獻者，恭喜！
|
||||
|
||||
1. **清理專案** 在 PR 被成功合併後， _清除專案(clean up)_ 會是一個好習慣。 你需要清除你的本地分支以及你的遠端數據庫分支。首先，你可以利用下列的指令清除本地分支：
|
||||
|
||||
```bash
|
||||
git branch -d [分支名稱]
|
||||
```
|
||||
|
||||
之後，請確保在 GitHub 頁面上刪除遠端分支。
|
||||
|
||||
`Pull request` 要求更新更動到「自己」的專案數據庫，這看起來很蠢。但管理者與核心組員必須謹慎地考量你的更動才能合併到專案的主分支中。這便是向管理者請求上傳許可。
|
||||
|
||||
一個 PR 提供比對以及討論的地方，解釋分支的意義、確認程式的合理性、留言與測試……等等。一個好的 PR 必須參照前述所說的提交紀錄準則。若你的 PR 有解決特定的 issue，記得標記在 PR 當中。使用 `#` 接在數字前面來標記 issue 編號，如 `#97`。
|
||||
|
||||
🤞 交叉比對每個程式環節都正確無誤後，專案管理者才合併你所作的更動 🤞
|
||||
|
||||
若要從 GitHub 遠端數據庫更新到目前的本地工作分支，使用：
|
||||
|
||||
`git pull`
|
||||
|
||||
## 如何貢獻網路上的開源軟體
|
||||
|
||||
首先，尋找一個你感興趣的數據庫，你會複製一份副本到自己的裝置上。
|
||||
|
||||
✅ 對新手而言，尋找「適合新手」的數據庫可以[搜尋 'good-first-issue' 標籤](https://github.blog/2020-01-22-browse-good-first-issues-to-start-contributing-to-open-source/)。
|
||||
|
||||
|
||||
|
||||
有許多方式來複製數據庫。 一種是利用 "clone" 整個數據庫的內容。可以使用 HTTPS、SSH 或是 GitHub CLI (Command Line Interface)。
|
||||
|
||||
打開終端機並輸入下列指令來複製數據庫：
|
||||
`git clone https://github.com/ProjectURL`
|
||||
|
||||
複製完後記得切換到正確的資料夾當中：
|
||||
`cd ProjectURL`
|
||||
|
||||
你也可以利用[Codespaces](https://github.com/features/codespaces)來打開專案，一款嵌入在 GitHub 中的雲端開發環境，或是使用[GitHub Desktop](https://desktop.github.com/)。
|
||||
|
||||
最後，你也可以下載數據庫的壓縮檔。
|
||||
|
||||
### 有關 GitHub 的小知識
|
||||
|
||||
你可以為別人打星星(star)、追蹤(watch)或分叉(fork)任何一個 GitHub 上的共享數據庫。打上星星的數據庫會出現在右上方的導航欄中。就像是書籤，但是是給程式碼用的。
|
||||
|
||||
專案內會有 issue 追蹤器。大多數的 issue 會在 GitHub "Issue" 的標籤內(有些Issue會由作者另外說明)，供大家進行討論。 Pull Requests 標籤內會有正在討論與審核的程式更動。
|
||||
|
||||
專案也會有討論區、寄信功能以及聊天室如 Slack、Discord 或 IRC。
|
||||
|
||||
✅ 花點時間觀察你的新專案，試著更新設定、新增描述、或架構成一個大型專案(像個大看板一樣！)。你可以創造出任何東西！
|
||||
|
||||
---
|
||||
|
||||
## 🚀 挑戰
|
||||
|
||||
找朋友一起編輯彼此的程式。共同建立一項專案、分叉程式、建立分支、合併更動。
|
||||
|
||||
## 課後測驗
|
||||
[課後測驗](https://nice-beach-0fe9e9d0f.azurestaticapps.net/quiz/4?loc=zh_tw)
|
||||
|
||||
## 複習與自學
|
||||
|
||||
了解更多：
|
||||
|
||||
[貢獻開源軟體](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution)
|
||||
|
||||
[Git cheatsheet](https://training.github.com/downloads/github-git-cheat-sheet/)
|
||||
|
||||
練習，練習，再練習！ GitHub 有提供很好的學習管道：[lab.github.com](https://lab.github.com/)
|
||||
|
||||
- [第一週在 GitHub 上](https://lab.github.com/githubtraining/first-week-on-github)
|
||||
|
||||
你能找到更資深的實驗內容。
|
||||
|
||||
## 作業
|
||||
|
||||
完成[第一週在 GitHub 上](https://lab.github.com/githubtraining/first-week-on-github)
|
||||
Reference in New Issue
Block a user