Plataforma Informativa de Tareas

Normas para la entrega de tareas

Los alumnos tienen que entregar las tareas vía git usando el repositorio que facilita los servidores de electrónica (vea como crear un repositorio y configurarlo). Para saber los criterios de evaluación, lea esta sección dedicada.

Los archivos que usted debe entregar son: un archivo readme en texto plano, una documentación simple en un archivo pdf, un makefile, y archivos fuente. Archivos adicionales a los solicitados, como archivos basura, ejecutables, u objetivo (.o) serán debidamente penalizados. Cualquier otro archivo que deba agregarse a la tarea, será notificado con anticipación.

La descripción detallada de los archivos a entregar se presenta a continuación:

• readme.txt

  Este texto menciona los archivos que componen la tarea, explica cómo se compilar cada etapa desarrollada (si requiere pasos o elementos extra, como bibliotecas por ejemplo), y cómo se debe ejecutar cada una de ellas; de tal forma que un usuario que no tenga conocimientos avanzados de programación sepa la función principal de su código y como llevarla a cabo.

  De ser necesario, otras cosas pueden ser agregadas para dar completitud al entendimiento de la tarea. Sólo debe generarse un archivo para toda la tarea, no es necesario generar uno por cada etapa desarrollada.

  En caso de que la tarea a realizar cuente con una etapa adicional que brinde una bonificación extra de puntaje, se debe especificar en el documento si se efectuó el desarrollo de la etapa.

• Documentación

  Corresponde a un documento en formato pdf donde se debe incluir un diagrama de alto nivel del desarrollo de la tarea (si el desarrollo es por etapas, el diagrama debe estar basado en la última etapa), una explicación breve de los módulos que componen a ésta, centrándose en la forma en que ellos interactúan y un breve listado con las dificultades presentadas durante el desarrollo de la tarea y las soluciones implementadas para abordarlas. En caso de no lograr solucionarlos, se debe señalar los elementos que hicieron falta para abordar el problema de mejor forma. Se espera que se mencionen por lo menos 3.

• Makefile

  Este archivo permite compilar los módulos de la tarea, de modo que al ejecutar el comando make en la respectiva carpeta de la etapa a utilizar, todos los archivos sean compilados y la tarea se encuentre lista para ser ejecutada. Si la tarea tiene mas de una etapa se debe generar un archivo makefile por cada etapa o módulo desarrollado.

• Archivos fuente (.c .cpp .java), de encabezado (.h) y otros

  El código debe ser estéticamente correcto (buen uso de espacios, saltos de linea y debe estar indentado). Esto facilita la lectura y la comprensión del flujo del código. Además, se en que los nombres de las variables y funciónes sean concisos y autoexplicativos (es decir, que su nombre no sea largo y además ofrezca indicios de lo que hacen). También se debe comentar el código para especificar el funcionamiento de las partes. Consejos para escribir código.

• Organización de Archivos

  Si el desarrollo de la tarea contempla mas de una etapa, cada una de estas debe estar almacenada en una carpeta diferente, con un nombre descriptivo (Etapa 1, Etapa A, etc). Esto permite la evaluación del método de desarrollo iterativo e incremental, permite un repositorio más ordenado y facilita la labor de corrección de ésta.

Norma de Atrasos: Se efectuará un descuento de 5 puntos por día de atraso cumplido (incluyendo sábados, domingos y feriados).

Procedimiento para entregar tareas

Las credenciales para ingresar al sitio les han sido entregadas vía e-mail. Cuando entren por primera vez, deben generar una contraseña usando un enlace seguro proporcionado en el mismo correo. Procuren anotarla en un lugar seguro, será necesaria para crear y administrar sus repositorios!.

Una vez allí, se debe crear un repositorio en los servidores de Electrónica con nombre alusivo al número de tarea y al ramo.

El repositorio debe tener como colaboradores a los ayudantes del ramo..

El título del repositorio creado para cada tarea debe cumplir con el siguiente formato:

apellido_alumno_1.nombre_alumno1 - apellido_alumno_2.nombre_alumno2 - apellido_alumno_3.nombre_alumno3 - TareaX.

Los archivos de la tarea deben estar subidos en el branch principal ("master"). Al realizar la ultima publicación, agregar tag "Final" al commit y realizar push con opción de tags habilitada:

La revisión de la hora/fecha de entrega se realizará con respecto al último commit del tag "Final". Si este tag no se encuentra en el repositorio, ¡la tarea no se considerará entregada!

Si tienen problemas usando GIT, pueden ver una pequeña referencia en el apartado Ayuda GIT.

Importante

Los repositorios deben ser privados, ver ultima sección de Crear repositorio GIT

Criterios de evaluación de tareas

Las tareas serán evaluadas de acuerdo a los siguientes criterios:

• Compilación (10%):

  Los programas compilan sin errores ni warnings. En caso de que durante la compilación se presenten errores pequeños que no entorpecen la ejecución de la tarea, se contactarán a los alumnos y se les dara una sola oportunidad para encontrar alguna solución, siendo éstos responsables de responder oportunamente.

  Si los errores son difíciles de corregir o no permiten la ejecución de la tarea, no se podrá comprobar si ésta cumple con los requisitos solicitados y por ende, éstos se evaluarán con un cero.

• Documentación General (30%):

  Se evalúan los archivos readme, makefile y de documentación, respetando los formatos indicados. Se entrega también gráficos e imágenes solicitadas en el enunciado de la tarea. Además, cada uno de los miembros realiza un uso apropiado del repositorio GIT, respetando las indicaciones dadas en esta sección.

• Cumplimiento De Requerimientos (60%):

  La tarea debe cumplir con cada uno de los hitos planteados para cada una de las etapas solicitadas.

  No se debe aplicar hard coding, que corresponde a la mala práctica de incrustar datos directamente en su código, en vez de obtenerlos a través de la ejecución de una rutina, lo que conlleva a resultados incorrectos. Por ello, su uso implica descuentos en el puntaje.

  Su trabajo debe hacer uso de las técnicas cubiertas en la asignatura y cuyo aprendizaje se busca evidenciar. Por ejemplo, si su solución debe ser orientada a objetos (caso ELO329), el no uso de este paradigma implicará descuentos

La división del puntaje en dichas secciones queda al criterio de los ayudantes, quienes se compromenten a aplicarla de igual forma a todos los estudiantes.

¿Qué poner en el archivo de documentación?

• Un diagrama de alto nivel del desarrollo de la tarea (si el desarrollo es por etapas, el diagrama debe estar basado en la última etapa), una explicación breve de los módulos principales utilizados en ésta y como interactúan entre ellos.
• Por lo menos se mencionan 3 dificultades encontradas durante el desarrollo de la tarea y como se solucionaron o que les hizo falta para solucionarlas.
• Incluir la información que usted estime importante para entender su solución.

Además:

• La explicación breve y las dificultades son elementos esenciales en el archivo de documentación y por ende tienen alta ponderación en el puntaje de éste. No olvidar añadirlas.

• Un código bien comentado, identado y autoexplicativo puede ahorrar escribir mucha documentación aparte. Se recomienda nombrar las variables de forma inteligente para hacer el código mucho más entendible tanto para ti como para el ayudante.

• Ojo, el buen cumplimiento del procedimiento de entrega también es evaluado como parte de la documentación.

¿Qué se espera en su proyecto del repositorio GIT?

• Todos los integrantes deben realizar un número similar de commits, con el fin de demostrar un dominio parejo grupal en el uso de esta herramienta.
• En general, el número de commits totales de la tarea deberá ser por lo menos igual al triple del número de etapas de la tarea.
• Se debe mantener la formalidad en los commits (usar comentarios sin lenguaje vulgar ni ofensivo)
• Los commits deben poseer información relevante, deben indicar los cambios realizados a los códigos resumidamente. No son aceptados commits que dicen solamente: “actualización”, “readme”, “etapa 1” .
• No se deben subir las etapas completadas inmediatamente, ni subir todos los códigos el mismo día de la entrega, sino que se sube el código a medida que es confeccionado. Esto presenta varios beneficios, tales como que si se realiza algún cambio que dañe su programa, tenga un respaldo de estados anteriores y pueda volver a dicho estado.

Crear y configurar un repositorio en servidores de Electrónica.

¿Por qué GIT?

La razón por la que se pide usar GIT es que permite tener un control de versiones. Es decir, si tienes un grupo de trabajo trabajando en distintos computadores, y quizás en muchas partes del mundo, como ocurre en muchísimos proyectos de código abierto, se necesita tener control sobre el código de los proyectos.

• Algún desarrollador haga algún aporte, y el resto del grupo decida si este aporte se convertirá en código definitivo para el programa.
• Si alguien modifica una parte sensible del código, haciendo que el resto no funcione, se pueda volver atrás fácilmente.
• Se lleve un comentario aparte sobre qué modificaciones necesita cada archivo (un TODO: to-do, "por hacer")
• Algún no-desarrollador quiera obtener la última versión del código fuente para compilarlo y usarlo en su propio computador; colaborando en probar el programa.

Instalando GIT

En Linux:

Las instrucciones asumen que tienes instalada una distribución tipo Debian (como Ubuntu o Linux Mint). Dependiendo de cuál sea tu distribución de Linux el manejador de paquetes puede variar. Por ejemplo, en el caso de que uses Arch Linux, debes cambiar apt-get install por pacman -S

En Windows:

Descarga e instala el programa: http://git-scm.com/download/win

Ejecución por Primera Vez

En Linux simplemente debes abrir la consola. En Windows debes abrir la consola GIT que puedes encontrar en Start > All Programs > Git > Git Bash. El resto de operaciones son idénticas entre las versiones de GIT de ambos sistemas operativos.

Primero debes indicarle a GIT tu nombre y correo. Eso se hace con los siguientes comandos (omitir signo $):

Creando un repositorio en el servidor de electrónica.

Todo alumno del ramo posee un usuario y contraseña en los servidores GIT de electrónica. Cada alumno debe tener en su poder, en su correo institucional, las credenciales para entrar al sitio. Lo primero que se necesita para manejar los repositorios es crear una contraseña de usuario, para lo cual se proporcionó en el mismo correo un link que permite hacerlo.

Para crear un repositorio se debe primero configurar una conexión segura con el servidor de electrónica. Para eso debe generarse un par de llaves RSA (una llave privada y una llave pública) que asegurará que la comunicación con el servidor será confiable. (Para curiosidades, se pueden encontrar mayores detalles sobre el cifrado RSA aquí).

Luego, en el servidor se debe debe conocer tu llave pública que se encuentra en el archivo .pub generado en la carpeta /home/user/.ssh/id_rsa si dejaste todo en blanco.

Entrar al servidor de electrónica, logearse e ir a "Profile Settings" (Parte superior derecha de tu dashboard), luego "Manage SSH keys" (menu parte izquierda), click en "add key", debes pegar el contenido del archivo público generado (el resultado de dicho comando cat) y apretar "Add Key". Ahora sí se puede crear el repositorio. En el terminal, si es primera vez que usa GIT, será necesario que proporcione información que lo pueda identificar.

Creando nuevo un repositorio (Desde Web)

En la plataforma web de electrónica dirigirse al dashboard y elegir la opción "Create a new project" y llenar la información que se requiere.

Configurando el repositorio

Una vez listo el paso anterior se le presentará información para configurar el git. Cree localmente una carpeta en donde contendrá el proyecto, un archivo README, y en ella ejecute los siguientes comandos:

Privatizar repositorio [Obligatorio]

Usted debe privatizar su repositorio, en caso de que exista copia todos los grupos involucrados serán culpables de la copia dado que o permitieron o copiaron siendo que no debería darse la oportunidad. para hacer su repositorio privado usted debe ir a dashboard elegir el repositorio dentro del menu your projects y finalmente en el menu de la derecha entrar a "manage access" y apretar en make private. Ahí mismo usted debe agregar las ids de sus compañeros de grupo para que puedan trabajar en equipo y la del ayudante (oscar.tapiab) para que pueda calificarlos.

Operaciones comunes para usar en GIT

La secuencia que debemos seguir en GIT es el siguiente:

1. Clonar o crear un repositorio localmente.

• Para Crear un repositorio localmente, debes ir al directorio principal de la tarea, y ejecutar ahí los comandos git init y git add .

cd carpeta/de/la/tarea
git init
git add .


Con init, inicializas la carpeta para que GIT pueda reconocer la información del proyecto. Con add . agregas todos los archivos que tiene la carpeta actual al repositorio. (debes usar git add cada vez que crees un nuevo archivo para indicarle a GIT que estás incluyendo un nuevo archivo al repositorio)

• Para clonar un repositorio, debes copiar un link que se proporciona en el sitio web del proyecto. Con eso puedes descargar todo el código fuente del proyecto. Por ejemplo, para descargar OpenCV debes usar:

git clone https://github.com/Itseez/opencv.git


2. Asociar la carpeta recién creada a tu repositorio creado en GitHub.

• En el sitio de GitHub de tu repositorio debe contener el link de tu proyecto. Debes asociarlo al branch principal del proyecto.

git remote add origin https://github.com/VirusRushTheater/elo330_tarea2.git

3. Realizar los cambios necesarios a los archivos necesarios.

• Agregas archivos al repositorio usando el comando:

git add [archivo]

• Puedes usar un punto (.) en lugar de [archivo] para incluir todos los archivos del directorio actual.

• Borras archivos del repositorio usando el comando:

git rm [archivo]

4. Hacer un commit: guardar los últimos cambios hechos al código en tu repositorio. Si quieres puedes agregar un comentario detallando los cambios generales que le hiciste a los archivos.

git commit -m [Comentario]

5. Enviar los cambios al servidor. Debes detallar a qué branch los quieres enviar. En este caso, lo haremos al branch origin.

git push -u origin master

Observación: dependiendo de su versión de git puede ser que requiera hacer mas configuraciones a su git, pero en ese caso al intentar hacer el push el mismo software le indicará qué debe configurar y le explicará correctamente, usted es capaz con esa información de tomar las decisiones que desee.

Si tienes dudas, puedes consultar una referencia ilustrada del proceso de creación de cuentas y repositorios en este archivo.

Ejemplo ilustrado del uso de GIT

Si alguno de estos pasos le pareció dificil o generó confusión, puede revisar el ejemplo ilustrado de uso de GIT

Documentación

Cheat Sheet con las operaciones principales en GIT.

Documentacón oficial

Branches

Trabajo remoto con Aragorn

Se explicará cómo conectarse a Aragorn desde un computador con sistema operativo Windows o con sistema opertaivo Linux. Además se explicárá como visualizar en pantalla las ejecuciones de aragorn a través de un servidor X.

Aragorn es el nombre del servidor para los alumnos de electrónica/telemática. Para trabajar en Aragorn, deben utilizarse programas de conexión SSH / SFTP. El método de conexión con Aragorn depende del sistema operativo que tengas instalado en tu computador.

El Kernel y versión instalada de Linux en Aragorn son:
Linux Aragorn 3.2.0-4-amd64 #1 SMP Debian 3.2.60-1+deb7u3 x86_64 GNU/Linux

Windows

En caso de Windows el cliente SSH como el servidor X no vienen instalados por defecto, por lo cual es necesario instalar software externo. El software que se explicará para los usuarios Windows es el mobaxterm que es de muy fácil uso y además tiene una versión portable.

Primero debes descargar la versión probada desde aquí.
Puedes encontrar la ultima versión del software a través de su página web.

Debes ejecutar el ejecutable que esta dentro del .zip, al ejecutarlo se abrirá una pantalla en la que por un lado se verá una consola de comandos, en la cual podrás ejecutar el comando ssh con la siguiente sintaxis:

Mobaxterm incluye tanto el cliente ssh como el servidor X por defecto. Puedes probar abrir un editor gráfico de texto llamado gedit, usando el siguiente comando (una vez logeado dentro de Aragorn).

Con las instrucciones anteriores debería aparecer una pantalla con gedit abierto listo para usar, ejecutándose remotamente desde Aragorn y simplemente la ves a través de una "ventana": su servidor X.

Linux

La mayoría de las distribuciones de Linux incluyen un cliente SSH preinstalado, de modo que no se hace necesario instalar software extra. Para conectarse a Aragorn vía SSH basta simplemente ejecutar el comando ssh en consola con la siguente estructura:

Para activar el servidor X en la conexión SSH y así poder visualizar, por ejemplo, un editor de texto como gedit debes agregar el flag -X a la ejecución del comando ssh, como se muestra a continuación.

Con las instrucciones anteriores debería aparecer una pantalla con el gedit abierto listo para usar pero que realmente está siendo ejecutada desde aragorn y usted la ve a través de su servidor X.

Copiar archivos desde y hacia Aragorn usando SCP

En el caso de que prefieras editar los archivos en tu propio computador y luego transferirlos a Aragorn, esto también se puede realizar. Para ello, se emplea el comando scp, la cual funciona como una versión SSH del comando cp. (para mayor información de este comando, ingresar en terminal man scp).

Copiar a un servidor remoto

Se debe incluir el nombre de archivo local (desde_local.txt), el servidor, nombre de usuario y la carpeta remota o nombre a la cual quieres enviar el archivo. (hacia_remoto.txt)

Copiar desde un servidor remoto

Igualmente puedes transferir un archivo remoto hacia tu computador. Simplemente debes poner el nombre del archivo remoto primero y luego el nombre de la carpeta local en la cual quieres dejar tu archivo.

Copia recursiva (carpetas enteras)

Para copiar carpetas enteras (en ambos casos), basta con añadir la opción -r (recursiva).

Ejemplo ilustrado del uso de MobaXterm

Si desea revisar un ejemplo de uso de MobaXterm, puede visitar el ejemplo ilustrado de uso de MobaXterm

Consultas a Ayudante

Ante consultas, inquietudes o consejos con respecto a las tareas, contactar a los ayudantes mediante el correo oficial del ramo elo329.utfsm@gmail.com ó a sus correos personales:

Marcelo Cárdenas: marcelo.cardenas.13@sansano.usm.cl

Toda información oficial se compartirá a través de la lista de correos .¡Recuerden verificar que se encuentren suscrito a ella!.

¿Para qué sirve esta Guía?

Esta es una guía rápida, simple y gráfica del uso de la herramienta GIT para las tareas del ramo. Destinada a alumnos sin ninguna experiencia previa con el uso del programa.

Para un enfoque más técnico acerca del uso de esta herramienta, se recomienda leer el apartado de Ayuda GIT.

Antes de Comenzar

► En caso de Windows: tener el programa GIT Bash instalado. Puedes descargarlo aquí.

► En caso de Linux: tener GIT instalado y utilizar la consola del sistema operativo en lugar de GIT Bash.

► Tener una cuenta en GIT ELO. (Las cuentas de GIT de informática no son compatibles).

Crear un Proyecto en Gitlab

Lo primero por hacer es iniciar sesión en la plataforma. Una vez realizado esto, pulsar el botón verde New Project para crear un nuevo proyecto.

Ojo: solo un integrante debe crear el repositorio, a los demás integrantes se les dará acceso posteriormente.

Como norma de las tareas, es obligatorio que el nombre del proyecto cumpla con formato apellido1.nombre1-apellido2.nombre2-apellido3.nombre3-Tarea[número de tarea]. Por ejemplo, para la tarea 1 un título adecuado es Marquez.Jesus-Arancibia.Pilar-Tarea1.

Además, el proyecto debe ser privado.

Una vez creado el proyecto, para poder acceder al repositorio desde Git Bash es necesario que actualicen su configuración actual copiando lo que está en Git Global Setup.

Si no han usado Gitlab antes les aparecerá una advertencia en la parte superior de la pantalla que les sugiere agregar su clave SSH. Sin esta clave no podrán actualizar su repositorio.

Si no cuentan con una clave y no han recibido la advertencia, pueden ir a configuración del usuario y buscar SSH Keys.

Para ver el procedimieto de registro de la llave SSH pueden ir al apartado Llave SSH.

Continuando con el proyecto, si desea copiar los archivos del repositorio a nuestro computador, necesitamos una carpeta local que esté vacía y accedemos a ella en GIT Bash.

Para ello, se debe hacer uso del comando cd, escribiendo dicho comando y luego la dirección de la carpeta dentro de su sistema, siguiendo un esquema como el siguiente: cd direccion/de/la/carpeta. Ojo con la orientación del slash, Git Bash no reconoce los "\".

Ya ubicados en la carpeta con GitBash, seguimos las instrucciones de la página de inicio de nuestro proyecto para convertir dicha carpeta en un directorio de repositorio Git.

En breve lo que hace cada comando es:

Clonar el proyecto en el repositorio (carpeta) local.

Dirigir a la direccion de la carpeta del repositorio.

Crear un archivo md llamado readme.

Agregar el archivo "README.md" al repositorio.

Generar un "commit", una especie de paquete con todos los archivos agregados por el comando add y con un mensaje instructivo que indica cuales fueron los cambios realizados en los archivos. En este caso se agrega el archivo README.md con el comentario "add README".

Subir el commit al repositorio.

Al subir el commit al repositorio, todos los archivos estarán disponibles para los demás integrantes del repositorio y los mensajes de los commits serán visibles en la página del proyecto, viendo así los cambios que realizó ese commit al proyecto y el comentario asociado al subirlo.

Para agregar miembros al proyecto ir a Settings -> Members en la parte izquierda de la pantalla.

Se deben de agregar los compañeros de grupo y los ayudantes de los dos paralelos.

Todos los roles deben ser Master

Unirse a un proyecto en Gitlab

El creador del proyecto debe haber generado una invitación para tí, con permisos como master o developer al proyecto. Por lo tanto podrás ver al inicio un enlace al proyecto del que eres parte y quien es el creador.

Para acceder a los archivos del repositorio, debes tener una carpeta vacía destinada a ser de repositorio. Utilizando GIT Bash ubicas la carpeta y luego inicias el programa administrador de git utilizando:

OJO: Debes registrar tu clave SSH en caso de no haberlo hecho antes. Ver Aquí.

Para que la carpeta remota reconozca el repositorio del proyecto es necesario hacer:

Una vez hecho esto, utiliza el siguiente comando para actualizar tu repositorio local con en del proyecto:

¡Ahora podrás ver los archivos del proyecto en tu repositorio local!.

Subir mis cambios al Proyecto

Al realizar cambios en el repositorio local (carpeta), puedes subir tus cambios para que el resto de los integrantes puedan acceder a ellos.

Para lograr eso, ejecutando GIT Bash, nos situamos en la dirección del repositorio local y luego iniciamos el programa administrador de git:

Luego indicamos los archivos que deseamos subir al repositorio con la siguiente sentencia.

Por otro lado, si deseamos agregar todos los cambios realizados en la carpeta al commit, ejecutamos:

Luego creamos el commit:

Y finalmente lo subimos a la página:

OJO: Es recomendable siempre actualizar el repositorio antes de un hacer un git push.

Descargar Actualizaciones del Repositorio

Para actualizar tu repositorio local en caso de que hayan habido cambios en el proyecto colocar:

Llave SSH

Esta llave es necesaria de registrar para todo los usuarios, sean creadores de proyectos o no.

Solo es necesario registrar la llave SSH una vez.

Lo primero que hay que hacer es copiar este comando en su GIT Bash.

Deberán de darle ENTER a todo, no es necesario poner nada.

Una vez hecho esto colocar el siguiente comando:

Copiar la respuesta.

Ejemplo gráfico:

Pegar la respuesta en Settings->SSH Keys y agregar llave.

Si les sale el siguiente error al intentar clonar el repositorio y ya han registrado su llave:

Puede solucionarse el problema copiando en GIT Bash el siguiente comando:

No es necesario volver a registrar una llave SSH para futuros proyectos en el mismo ordenador.

Para qué sirve esta guía

Esta es una guía, rápida y simple, de cómo utilizar funciones básicas de MobaXterm para las condiciones del ramo. Destinada a alumnos sin ninguna experiencia previa con el uso del programa.

Iniciar sesión en Aragorn

Una vez abierto el programa, dirigirse al botón de Session que se encuentra en la parte superior izquierda de la interfaz

Se abrirá otra ventana, en la que deben presionar el botón SSH, en la esquina superior izquierda.

La interfaz mostrará la configuración para esta opción, en la cual es necesario colocar la dirección host en donde queremos conectarnos. Para este caso, la dirección de Aragorn es aragorn.elo.utfsm.cl.

No es necesario editar nada más.

Nos pedirán el nombre de usuario que viene siendo el nombre del correo institucional (no el correo completo).

Luego, la contraseña es la misma del correo institucional.

Repositorio

El sector izquierdo de la interfaz es el repositorio personal. Ahí podrás crear carpetas y colocar archivos desde tu pc solo arrastrandolos hacia el lugar.

Finalmente, se comienza la sesión en la dirección del repositorio, por lo que para acceder a tus carpetas desde la terminal puedes usar el comando cd y el nombre de la carpeta

La terminal de Aragorn es prácticamente una terminal de Linux, por lo que se recomienda estudiar los comandos básicos para su uso.