- 1. Setting Up
- 2. Local Development
- 3. Opening a Pull Request
- Questions?
- Troubleshooting
If you are new to open source, we recommend reading GitHub's open source guide and their Hello World tutorial.
Feel free to contribute to the Techqueria website in one or more of the following ways and thank you for being willing to help out! 😊
- Tackle any of the open issues that are labeled
help wanted,good first issueorhacktoberfest.- If an issue has the label
in progress, someone is already working on it. - If an issue has the label
admin, an admin probably needs to get involved since it requires admin access. - Even if an issue has someone assigned, it still might need extra help so check it out if it appeals to you!
- If an issue has the label
- Open a new issue
- Report a bug
- Request a new feature
- Improve our contributing guidelines (this file) or other documentation
- Fix typos or grammar errors on pages or across the code base
- Refactor code
- Anything else you can think of! 😆
Fork this repository and clone it locally.
Connect your local to the original "upstream" repository by adding it as a remote.
Pull in changes from "upstream" often so that you stay up to date so that when you submit your pull request, merge conflicts will be less likely.
See more detailed instructions through this GitHub article called "Syncing a Fork".
If you've never used npm before, we recommend following these instructions to get
npmup and running properly.
npm installThis will install all the packages needed to run this website locally.
npm startThis will automatically open a browser tab with the website and BrowserSync will automatically reload the CSS or refresh the whole page, when stylesheets or content changes.
At this point, you are able to preview the website locally and can make changes to the source code.
Our pipeline was inspired by Victor Hugo which is a Hugo boilerplate for creating truly epic websites.
You can view https://techqueria.org/about/brand as a reference for how we tackle our organization branding.
We are using Workbox to register a service worker on the production version of the website.
A service worker allows users to view the homepage of Techqueria even when they are offline and therefore caches the necessary assets.
❗ If you see a console error complaining about the service worker not registering while developing locally, that's okay! The service worker registration should fail in development since we don't want caching.
- Hugo
- static site generator or CMS
- Bulma.io
- design system
- Gulp
- Webpack
- asset pipeline
- Workbox to create a service worker
- Babel
- JavaScript compilation and transpilation
- Twemoji
- Emoji rendering the same regardless of platform or browser
- Font Awesome
- Standardized icons
- Netlify
- hosting and deployment
- JavaScript
- SASS
- HTML
- TOML
- JSON
Content is in the progress of being translated to Español.
The language dropdown is located at site/layouts/partials/footer/language-dropdown.html which is referenced at site/layouts/partials/footer/who-we-are.html. It is currently disabled until parent pages are translated.
Language names are configured using site/data/i18n/languages.toml. For now, these only have English and Español but more can be added.
Translated strings can be located at site/i18n/en.toml and site/i18n/es.toml
Here's an example of translating one string from the who-we-are.html layout template.
The syntax for translated strings in the HTML is
{{ i18n "translation_id" }}.
<!-- who-we-are.html -->
<p>{{ i18n "join_us" }}</p>The translation IDs must be the same in both
en.tomlandes.toml.
# site/i18n/en.toml
[join_us]
other = "Join us and share your experience with Techqueria."# site/i18n/es.toml
[join_us]
other = "Únete a nosotros y comparte tu experiencia con Techqueria."Here's an example of translating the "Brand" page in Markdown.
So for Markdown pages to be translated in Spanish, add an identical file with .es.md at the end.
site/content/about/brand.md
title: Brand 🎨
description: Download our assets and discover our style guide.
site/content/about/brand.es.md
title: Marca 🎨
description: Descarga nuestros recursos y descubre nuestra guía de estilo.├── .github
| ├── CODE_OF_CONDUCT.md // code of conduct
| ├── CODEOWNERS // automatic reviewers for certain files and directories
| ├── CONTRIBUTING.md // how to contribute
| ├── ISSUE_TEMPLATE.md // template for new issues
| ├── PULL_REQUEST_TEMPLATE.md // template for new pull requests
| └── stale.yml // configuration for Stale bot
├── .vscode
| └── settings.json // VS Code workspace settings
├── dist // (ignored) static files generated and served through Netlify using npm start or npm build
├── site // HUGO site folder
| ├── archetypes // default post formats
| ├── content // content goes here (Markdown files with posts and pages)
| ├── data // languages configuration
| ├── i18n // translations for strings in HTML layouts
| ├── layouts // HTML Liquid templates for pages
| ├── static // files that go into root of dist directory
| └── config.toml // configuration file (Hugo)
├── src // folder of assets handled by Gulp/Webpack
| ├── img // images are optimized through Gulp
| ├── js // compressed and transpiled to a single JS file
| └── sass // compressed and compiled to a single CSS file
├── _redirects // redirect configuration for Netlify
├── .babelrc // configuration for Babel
├── .editorconfig // configuration for editors
├── .eslintrc // configuration for ESLint
├── .gitignore // ignored files and folders
├── .hound.yml // configuration for Hound (GitHub integration)
├── .nvmrc // configuration for NVM
├── .prettierrc // configuration for Prettier formatter
├── CNAME // domain name
├── gulpfile.babel.js // configuring Gulp build process for assets
├── LICENSE // repo license
├── netlify.toml // configuration for Netlify deployment
├── package.json // managing NPM packages
├── README.md // overview
├── renovate.json // configuration for Renovate bot
├── webpack.dev.js // Webpack build configuration for local development
└── webpack.prod.js // Webpack build configuration for production
References
package.jsonandgulpfile.babel.js
We've covered one of them already - npm start - here are the others.
npm build- Build production ready files
npm build:dev- Build local files
npm start- Local server for development
npm start:prod- Local server for production ready website
npm start:preview- Preview draft and future posts.
npm lint- This will report any ESLint issues within the command line.
We use Google's Lighthouse to check for performance, accessibility, SEO, our PWA score and to make sure we follow best practices.
If you are using Chrome, Lighthouse is the default audit system so it's easy to use!
As of October 2018, we have scores of 100 or close to that for every metric and we strive to keep it that way through automated checks in PRs (see more below).
Heads up, you do not need to run this command for development purposes.
npm run buildThis will build a static version of the website inside the /dist folder.
This command is just used to handle production deployments through Netlify and does not need to be run locally - refer to netlify.toml and gulpfile.babel.js.
Make sure to do the following when opening your pull request (or PR)
- include a useful description of your PR after opening it
- make sure all the checks have been filled out
- reference any relevant issues or supporting documentation in your PR (for example, "Closes #37.")
Below is an example of what the Markdown for a good PR looks like.
Notice it has a with a description with a reference to an existing issue. It also has all the checks filled in with an x.
This adds a contact form to the website using Bulma - fixes #92.
---
<!-- Thank you for contributing to Techqueria, it is much appreciated! 😊 -->
<!-- Before creating a PR, make sure to verify the following. -->
> ✅️ By submitting this PR, I have verified the following
- [x] Checked to [see if a similar PR has already been opened](https://github.com/techqueria/website/pulls) 🤔️
- [x] Reviewed the [contributing guidelines](https://github.com/techqueria/website/blob/master/.github/CONTRIBUTING.md) 🔍️
- [x] Added my name to the bottom of the list under the **Contributors** section in the [README.md](https://github.com/techqueria/website/blob/master/README.md) with a link to my personal website or GitHub profile 👥️We use several GitHub integrations/bots to make it easy to catch errors for every new PR created.
Here's an example of how that would look like for a great PR.
- AccessLint
- tests accessibility
- Codacy, CodeFactor, Codebeat and LGTM
- automated code reviews and code analytics
- Netlify Deploy Previews
- see how your changes would look like in production
We are using Waffle.io to track open issues and progress being made.
There are 2 labels being used to track progress - these are used Wafflebot to automate most of the process.
-
in progressMaintainers are responsible for adding the label
in progressonce someone has decided to take on an open issue. -
reviewA PR has been opened and references a specific issue.
If after a week you haven't heard from any of the maintainers, please mention @techqueria/admins in the PR.
If you have any questions, comments, concerns or general feedback, we're happy to help!
Please make a comment mentioning @techqueria/admins in your issue or PR and one of us will get back to you ASAP.
If you are part of the Techqueria Slack workspace, we also have a dedicated #website channel for discussion and a #website-gh for GitHub notifications.
If needed, there is also the option of emailing us using organizers@techqueria.org.
Try rm -rf node_modules and then npm install again.
Outdated pages, service worker still loading on local development
Try running npm run clean - this will delete the dist directory.
You can then run npm start to spin up a local server.