site www
1.0.0
El sitio de documentación para el lenguaje de programación DART, construido con un altavuasis y alojado en Firebase.
¡Agradecemos las contribuciones de todo tipo! Para configurar el sitio localmente, siga las pautas a continuación en la construcción del sitio. Para obtener más información sobre cómo contribuir a este repositorio, consulte las pautas que contribuyen.
Comience buscando un problema que atraiga su interés o cree un problema con su cambio propuesto. Considere agregar un comentario para que todos sepan que están trabajando en ello y no dude en hacer cualquier pregunta que tenga sobre el mismo problema.
Para actualizar este sitio, bifurca el repositorio, realiza sus cambios y genere una solicitud de extracción. Para cambios pequeños y contenidos (como el estilo y las correcciones de error tipográfico), probablemente no necesite construir este sitio. A menudo puedes hacer cambios usando la interfaz de usuario de GitHub. Podemos organizar los cambios automáticamente en su solicitud de extracción.
Importante
Si está clonando este repositorio localmente, siga las siguientes instrucciones sobre la clonación con su submódulo.
Si su cambio involucra muestras de código, agrega/elimina páginas o afecta la navegación, considere construir y probar su trabajo antes de enviar.
Si desea o necesita construir el sitio, siga los pasos a continuación.
Para los cambios más allá de los simples ajustes de texto y CSS, recomendamos ejecutar el sitio localmente para habilitar un ciclo Edit-Refresh.
Instale las siguientes herramientas para construir y desarrollar el sitio:
Se requiere la última versión estable de DART para construir el sitio y ejecutar sus herramientas. Este puede ser el dardo incluido en el SDK Flutter. Si no tiene DART o necesita actualizar, siga las instrucciones en Get the Dart SDK.
Si ya tiene DART instalado, verifique que esté en su ruta y ya en la última versión estable:
dart --version
Se requiere la última versión estable LTS de Node.js para construir el sitio. Si no tiene Node.js o necesita actualizar, descargue la versión correspondiente de su computadora y siga las instrucciones desde el archivo de descarga de nodo.js. Si lo prefiere, puede usar un administrador de versiones como NVM y ejecutar nvm install desde el directorio raíz del repositorio.
Si ya tiene el nodo instalado, verifique que esté disponible en su ruta y ya en la última versión estable (actualmente 20.14 o posterior) :
node --version
Si su versión está desactualizada, siga las instrucciones de actualización sobre cómo la instaló originalmente.
Nota
Este repositorio tiene submódulos Git, que afecta cómo lo clona. La documentación de GitHub tiene ayuda general en los reposadores de bifurcación y clonación.
Si no es miembro de la organización DART, le recomendamos que cree una bifurcación de este repositorio en su propia cuenta, y luego envíe un PR de esa bifurcación.
Una vez que tenga un bifurcado (o sea un miembro de Dart Org), elija una de las siguientes técnicas de clonación de submódulos:
Clon el repositorio y su submódulo al mismo tiempo usando la opción --recurse-submodules :
git clone --recurse-submodules https://github.com/dart-lang/site-www.git
Si ya ha clonado el repositorio sin su submódulo, ejecute este comando desde la raíz del repositorio:
git submodule update --init --recursive
Nota
En cualquier momento durante el desarrollo, puede usar el comando git submodule para actualizar submódulos:
git pull && git submodule update --init --recursive
Antes de continuar configurando la infraestructura del sitio, verifique las versiones correctas de Dart y Node.js están configurados y disponibles siguiendo las instrucciones para obtener los requisitos previos.
Opcional: después de clonar el repositorio y sus submódulos, cree una rama para sus cambios:
git checkout -b <BRANCH_NAME>
Desde el directorio raíz del repositorio, obtenga las dependencias de DART del sitio.
dart pub get
Instale pnpm utilizando su método de instalación preferido. pnpm es un administrador de paquetes alternativo y eficiente para paquetes NPM. Si ya tiene pnpm , verifique que tenga la última versión estable. Recomendamos usar corepack para instalar y administrar versiones pnpm , ya que está incluido con la mayoría de las instalaciones de Node.
Si no ha usado corepack antes, primero deberá habilitarlo con corepack enable . Luego, para instalar la versión pnpm correcta, desde el directorio raíz del repositorio, ejecute corepack install :
corepack enable
corepack install
Una vez que tenga pnpm instalado y configuración, obtenga las dependencias NPM del sitio utilizando pnpm install . Le recomendamos encarecidamente que use pnpm , pero también puede usar npm .
pnpm install
Desde el directorio raíz, ejecute la herramienta dash_site para validar su configuración y conocer los comandos disponibles.
./dash_site --help
Desde el directorio raíz, sirva el sitio localmente.
./dash_site serve
Este comando genera y sirve el sitio en un puerto local impreso en su terminal.
Vea sus cambios en el navegador navegando a http: // localhost: 4000.
Tenga en cuenta que el puerto puede ser diferente si se toman 4000 .
Si desea verificar la salida y estructura HTML sin procesar, ver el directorio _site en un explorador de archivos o un IDE.
Haga sus cambios en el repositorio local.
El sitio debe reconstruir automáticamente la mayoría de los cambios, pero si algo no se actualiza, salga del proceso y vuelva a ejecutar el comando. Se planean mejoras a esta funcionalidad. Abra un nuevo problema para rastrear el problema si esto ocurre.
Comprometer sus cambios a la sucursal y envíe su PR.
Si su cambio es grande o le gustaría probarlo, considere validar sus cambios.
Consejo
Para encontrar comandos adicionales que pueda ejecutar, ejecute ./dash_site --help desde el directorio raíz del repositorio.
Si ha realizado cambios en el código en los directorios /examples o /tool , confirme su trabajo, luego ejecute el siguiente comando para verificar que esté actualizado y coincida con los estándares del sitio.
./dash_site check-all
Si este script informa algún error o advertencia, aborde esos problemas y vuelva a ejecutar el comando. Si tiene algún problema, deje un comentario sobre su problema o solicitud de extracción, y haremos todo lo posible para ayudarlo. ¡También puede chatear con nosotros en el canal #hackers-devrel en la discordia de los contribuyentes de Flutter!
Una compilación que falla con el Error: Some code excerpts needed to be updated! significa que uno o más extractos de código en los archivos de Markdown del sitio no son idénticos a las regiones de código declaradas en los archivos .dart correspondientes.
Para resolver este error, desde la raíz del directorio site-www , ejecute ./dash_site refresh-excerpts .
Para obtener más información sobre cómo crear, editar y usar extractos de código, consulte la documentación del paquete de actualizadores de extractos.
Las solicitudes de extracción enviadas pueden ser organizadas automáticamente por un mantenedor del sitio. Sin embargo, si desea organizar el sitio usted mismo, puede construir una versión completa y subirla a Firebase.
Si aún no tiene un proyecto Firebase,
Navegue a la consola Firebase y cree su propio proyecto Firebase (por ejemplo, dart-dev-staging ).
Regrese a su terminal local y verifique que haya iniciado sesión.
firebase login
Asegúrese de que su proyecto exista y active ese proyecto:
firebase projects:list
firebase use <your-project>
Desde el directorio raíz del repositorio, cree el sitio:
./dash_site build
Esto construye el sitio y copie a su directorio local _site . Si ese directorio existiera anteriormente, se reemplazará.
Implementar en el sitio de alojamiento predeterminado de su proyecto Firebase activado:
firebase deploy --only hosting
Navegue a su PR en GitHub e incluya el enlace de la versión escenificada. Considere agregar una referencia a la confirmación que organizó, para que los revisores sepan si se han realizado más cambios.
