Skip to content

CONTRIBUTING.es.md

Latest commit

聽

History

History
176 lines (120 loc) 路 11.1 KB

CONTRIBUTING.es.md

File metadata and controls

176 lines (120 loc) 路 11.1 KB
Raw

Como comunidad le damos la bienvenida a cualquiera que desee escribir y enviar publicaciones al blog de Playful Programming. En este documento revisaremos los pasos necesarios para crear una nueva publicaci贸n, y despu茅s enviarla a PP como una pull request o solicitud para incorporar cambios.

Note

Para un tutorial m谩s general sobre c贸mo contribuir a un proyecto con GitHub podr铆as revisar la gu铆a "Primeras contribuciones" antes de seguir leyendo esta p谩gina.

Algunos puntos a tomar en cuenta cuando escribas tu art铆culo:

  • 隆S茅 incluyente! En PP apoyamos a los desarrolladores de todos los niveles de experiencia - no excluyamos a los novatos ni desanimemos a los lectores que desean aprender algo nuevo.
  • Busca proporcionar informaci贸n relevante y verdadera - 隆Te recomendamos citar las fuentes de tu trabajo!
  • Mant茅n tu contenido imparcial; es decir, no hagas anuncios de productos o servicios sin ninguna raz贸n.

Si en alg煤n momento te sientes bloqueado o tienes alguna duda que quieras resolver, no dudes en abrir un reporte de problema en GitHub o bien comun铆cate con nosotros en Discord. 隆Estaremos encantados de ayudarte!

Contenido:

  1. Crear un perfil de autor
  2. Escribir una nueva publicaci贸n
  3. Traducir una publicaci贸n del blog
  4. Enviar una pull request

Crear un perfil de autor

Antes de crear una nueva publicaci贸n, deber谩s a帽adir informaci贸n acerca de ti. Para lograr eso, crea una nueva carpeta en content/ con tu nombre de usuario, y agrega un archivo index.md dentro de 茅sta; por ejemplo: content/eric/index.md.

Veamos un ejemplo de c贸mo se ver铆a tu archivo index.md:

---
{
  // "name" ser谩 tu nombre a mostrar, como quieras 
  // que se vea en tus publicaciones
  name: "Eric el Programador",

  // "firstName" y "lastName" son necesarios para
  // las etiquetas de OpenGraph - llena estos campos con los datos
  // que consideres apropiados
  firstName: "Eric",
  lastName: "el Programador",

  // "description" es una biografia corta que se mostrar谩 en tu p谩gina de perfil
  description: "Programador Haskell, escritor de fanfictions, un unicornio omnisciente.",

  // Tus usuarios de redes sociales pueden incluir "twitter", "github", "gitlab",
  // "linkedIn", "twitch", "dribbble", "mastodon", "threads", "youtube",
  // "bluesky", y "cohost", adem谩s de un "website" que 隆puede ser lo que quieras!
  socials: {
    mastodon: "https://hachyderm.io/@playfulprogramming",
    github: "playfulprogramming",
    website: "https://playfulprogramming.com/"
  },

  // Los "pronombres" son opcionales, pero recomendamos que los incluyas en tu perfil
  pronouns: "they/them",

  // "profileImg" es el valor de una imagen que debe estar en la misma ubicaci贸n de este archivo
  // - de preferencia con formato PNG/JPEG y al menos 512px de resoluci贸n
  profileImg: "./profile.png",

  // El campo "roles" reflejar谩 c贸mo vas a contribuir al sitio - si vas a
  // crear una publicaci贸n, solo definelo como "author", pero existen m谩s roles
  // 隆Hay roles para programadores y traductores tambi茅n!
  roles: ["author"]
}
---

驴No quieres mostrar tu foto real en el sitio? 隆Est谩 bien! Tenemos bastantes emoticones de unicornio personalizados que puedes usar como imagen de perfil. 隆Son adorables, ve a verlos! 馃ぉ

Una vez que tengas creado tu perfil, puedes ir al siguiente paso...

Escribir una nueva publicaci贸n

Todas las publicaciones en Playful Programming est谩n dentro de una carpeta: content/{username}/posts/ - estructuramos esto con una subcarpeta para cada publicaci贸n, que contiene un archivo markdown llamado index.md. El nombre de la carpeta con la publicaci贸n coincidir谩 con su URL dentro del sitio.

驴Eres nuevo con Markdown?

驴Revisa el documento Markdown Cheatsheet para ver ejemplos de c贸mo dar formato a distintos tipos de contenido en este archivo!

Cuando escribas tu publicaci贸n, necesitar谩s incluir metadatos en el frontmatter en la parte superior del archivo:

---
{
  title: "Mi primera publicaci贸n en el blog",
  description: "隆脡sta es mi primera publicaci贸n en el sitio de Playful Programming!",
  published: '2023-04-11',
  tags: ["meta"],
  license: 'cc-by-4'
}
---

隆Hola! 隆脡sta es mi primera publicaci贸n! (TODO: escribir m谩s texto aqu铆)

Nota: El t铆tulo que definas en el campo "title" siempre se ver谩 en la parte superior de tu publicaci贸n. No necesitas iniciar tu publicaci贸n con otro encabezado - de lo contrario 隆tu publicaci贸n tendr谩 dos t铆tulos!

Propiedades opcionales

Existen algunas propiedades extra que podr铆as incluir en el frontmatter de tu publicaci贸n, pero que no son necesarias:

  • authors: ["autor1", "autor2"] se puede usar para especificar de forma manual los ID's de los autores de una publicaci贸n en caso de que la publicaci贸n tenga varios autores.
  • edited: "2023-10-21" sirve para especificar la fecha en la que hiciste la "煤ltima actualizaci贸n" de tu publicaci贸n en caso de que realices modificaciones.
  • collection: "Mi genial serie de art铆culos" tratar谩 a un grupo de publicaciones como una serie en caso de que todas tengan el mismo texto collection configurado.
  • order: 0 reordenar谩 las publicaciones de una colecci贸n de acuerdo con el valor que proporciones. Esto no tendr谩 efecto a menos que la publicaci贸n se encuentre dentro de una colecci贸n.
  • originalLink: "https://example.com" especifica una URL externa que sirva como fuente para tu publicaci贸n. 隆Es importante especificar este valor si est谩s republicando algo que tengas escrito en otro blog!

Licencias

Proporcionar una licencia ayuda a explicar lo que los lectores pueden hacer con tu trabajo - ya sea que puedan usarlo como material para un curso o reusarlo en otras formas. Visita el sitio de Creative Commons para obtener una descripci贸n general de lo que se permite hacer dentro de los distintos tipos de licencias.

Actualmente, estas son las licencias de creative commons que se permiten como valores dentro de la propiedad "license":

Tambi茅n puedes omitir la propiedad "license". En este caso, tu publicaci贸n quedar谩 bajo la licencia MPL 2.0 del repositorio.

Enlaces incrustados

Las publicaciones pueden incrustar sus propias etiquetas <iframe> si es necesario - 茅stas mostrar谩n una vista previa de "haz clic para ejecutar" y no afectar谩n el tiempo de carga de la p谩gina.

Tambi茅n puedes incrustar algunos servicios de terceros simplemente pegando el enlace en tu publicaci贸n, como videos de YouTube o de Twitch, publicaciones de Twitter - y cualquier opci贸n soportada por oembed.com.

Im谩genes y videos

Si a帽adiste enlaces a im谩genes o videos, necesitar谩s guardar esos archivos en la misma carpeta que tu publicaci贸n y cambiar tu documento markdown para que haga referencia a 茅stos de forma local:

![Ferris, la adorable mascota crust谩cea de Rust](./ferris.png)

隆Aseg煤rate de incluir un texto alt descriptivo! Toma en cuenta qu茅 informaci贸n agregan esas im谩genes a tu publicaci贸n, y qu茅 contexto podr铆a ser importante para los lectores con capacidades visuales diferentes.

Los v铆deos tambi茅n se pueden incrustar con la siguiente sintaxis:

<video src="./ios_vs_android.mp4" title="Una comparaci贸n de c贸mo se aplica el espaciado de texto en iOS y Android"></video>

Cuando sea posible, los elementos <video> deber谩n elegirse por sobre los archivos .gif u otras im谩genes animadas en tus publicaciones. Esto es por motivos de accesibilidad - los v铆deos dan m谩s control a los usuarios acerca de cu谩ndo y c贸mo es que la animaci贸n se reproduce.

Traducir una publicaci贸n del blog

Si quires agregar una traducci贸n, primero aseg煤rate de crear un Archivo de datos de autor con el rol de "translator", 隆As铆 podr谩s recibir cr茅dito por tu trabajo en el sitio!

Para crear un archivo de traduccci贸n para una publicaci贸n, copia su archivo index.md y ren贸mbralo a index.(lenguaje).md, donde (lenguaje) es el idioma al que traduces la publicaci贸n. Por ejemplo, una traducci贸n al fr (franc茅s) podr铆a ser nombrada index.fr.md. El contenido dentro de este archivo puede ser traducido a su idioma respectivo.

Si fuera necesario traducir cualquiera de las im谩genes usadas en la publicaci贸n, estas deber谩n ser nombradas de forma similar - por ejemplo, una traducci贸n de dom_tree.svg deber谩 ser nombrada dom_tree.fr.svg.

Cualquier enlace a esas im谩genes deber谩 ser actualizado en el archivo index.fr.md de la publicaci贸n para que apunte a la imagen traducida.

Como referencia, los c贸digos de cada idioma los puedes consultar en el archivo /content/data/languages.json - si el idioma que quieres usar no se encuentra tal vez sea necesario que lo agregues.

Encontrar un c贸digo de idioma

Cada c贸digo de idioma dentro de /content/data/languages.json deber铆a estar formado de dos letras en min煤scula. Si incluye una regi贸n, agrega un guion seguido de otras dos letras en min煤scula. Por ejemplo, el c贸digo para el franc茅s es fr - para referirse al dialecto del franc茅s que se habla en Canad谩, el c贸digo ser谩 fr-ca.

Por favor usa - en lugar de _ en los formatos ISO de la regi贸n del idioma. En lugar de fr_ca, deber谩 ser fr-ca.

Consulta la lista Wikipedia: List of ISO 639-1 codes para conocer los identificadores que usar谩s en este formato.

Enviar una Pull Request

Una vez que hayas hecho todos los cambios, crea una Pull Request para agregar tu publicaci贸n al sitio.

  • Abre una nueva Pull Request desde tu fork (bifurcaci贸n).
  • Revisa que todos tus archivos est茅n dentro de la Pull Request, y que estos est茅n siendo combinados a la rama principal o main.
  • Crea el PR y espera a que quien mantiene el sitio lo revise.
  • Una vez combinada (merged), 隆tu publicaci贸n ser谩 visible en el sitio!

隆Nos pondremos en contacto contigo si tenemos alguna duda o retroalimentaci贸n cuando revisemos tu publicaci贸n!