Hey, welcome! This document should give you all the steps you need to make contributions to the Glitch community site. This guide applies to full time makers of Glitch as well as all members of our Glitch community.
Please note we have a code of conduct, please follow it in all your interactions with the project and the denizens thereof.
We also having a style guide discussing our coding conventions, styles, and goals.
Anyone in our community can feel welcome and supported in submitting improvements, fixes, and ideas to this Glitch community site.
Our contribution flow is built around a hunger for creative expression. Build things fast, with glitch, and share them. Here's how:
- You remix this site, play with it, and show us what you made! Tweeting @Glitch or posting to our forum are good ways to get our attention.
- We say something like "We like what you got, good job!"
- Your changes (or something inspired by your changes) are prepared and make their way to our live production site.
This site is open source. All interactions between this site and Glitch-the-application are using public API endpoints-- there aren't any special privileges or secret endpoints going on.
This site is also young and hungry. We don't have a public "bug list" and a lot of processes that are best to formalize have yet to be. And this site believes in a Glitchy future-- it is built, maintained, and deployed entirely within Glitch itself. We're living the Glitchy future of web development, and it's a blast.
Accessible technologies are important to allowing people to contribute. As we internally work on the code, we'll move incrementally towards ever-stronger documentation for the special pieces of this site and "boring"(easy to learn, perfectly fine) solutions for the standard components.
Behind the scenes, we'll make use of GitHub's Pull Request workflow to incorporate changes into the site. If you're a part of the GitHub community, then feel free to submit pull requests directly-- if you're not, don't worry about it and just focus on building cool stuff and sharing your ideas.
First, remix from https://glitch.com/~community into, e.g., my-remix
Next, make your changes. When you've got something you like, share it with us (see above), and you're all set.
If you're a core contributor or just really love Git, then read on.
Ok cool, these next steps are what we'd do internally and you're welcome to follow them as well if you choose. Beyond this point, there be 🐉s.
(Do this once per computer to create a local repository)
Remember to set up Git SSH or the Windows Client to get your auth in order.
# 1. On your local machine, clone our git repository from Github:
git clone [email protected]:FogCreek/Glitch-Community.git
# 2. Inside of your new repo, add a remote endpoint for our live site:
cd Glitch-Community
git remote add live https://api.glitch.com/community/git
(Do this once per remix/PR)
We're going to add a branch named after your remix, and set up a remote endpoint pointed at its git repo in glitch. We're using my-remix as a placeholder for your project name. Swap that out in the scripts below.
In your local repository,
# 1. Add your remix as remote source
git remote add my-remix https://api.glitch.com/my-remix/git
# 2. Fetch your remix into a new branch of the same name
git fetch my-remix master:my-remix
# 3. Switch to your new branch
git checkout my-remix
# 4. Push your branch to github
git push origin my-remix
Now you can use the GitHub UI to turn your branch into a pull request.
It's good practice to share a link to your project in the PR and talk about the functional changes you've made. This allows the reviewers to easily visit your remix to test out your new behavior.
(Don't have permission to push to github? You'll need to first Fork our repository and then create a pull request from the fork instead.)
(Do this when you've made more changes in Glitch that you want to include in the PR.)
In your local repository,
# 1. Make sure we're on the right branch
git checkout my-remix
# 2. Pull from Glitch into your local branch.
git pull my-remix master
# 3. Update the PR in Github
git push origin my-remix
And you're all set.
Keep your PR's small! (Days of work, not weeks.) This will save you from having to think about and use all of the more advanced git hyjinks to keep your PR in sync with master (not documented here, because there would be over 9000 🐉's. )
Note: Glitch apps make git commits (we call them checkpoints) every 10 minutes. If you make some quick changes, they may not show up in your diff on the Github pull request. If that is the case, you can either wait several minutes for the checkpoint to be made, or toggle Glitch Rewind on-and-off (which will force a checkpoint).
Only employees of Glitch will be able to do this step, and here it is!
You should perform these steps immediately after clicking the "Merge pull request" button on your PR in Github.
Be present in our #community chat room and say that you're starting a deploy and what you're deploying.
Keep a passive eye on the chat room while you work, in case anyone needs to talk to you about it while you've got it in flight.
We need to make sure any live changes are merged and happy. This is a Glitch site, after all-- we're not forcing the PR workflow, especially for small changes.
In your local git repository:
# Make sure we're in the right place and up to date.
git checkout master
git pull
# Pull in any live changes that aren't yet in Master:
git pull live master
# Merge if needed
# [ This is on you. 🐉 ]
# Then push these changes back up to github
git push origin master
Ok, now the GitHub repository is updated and stable.
We're going to put our release candidate onto community-staging.glitch.me.
Go to https://glitch.com/~community-staging and open up the console.
git log -1 # Prints out a stable changeset in case we need it.
git pull # Update us to master.
# That last step should never need to merge.
# If it does, something went wrong or somebody edited community-staging directly.
# Ask Jude or Greg for help.
refresh # Update the Glitch editor with the new files and kick off the build.
Now open up the logs and wait for the build to finish, then test your stuff.
protip: while you wait for the build to complete, use this time to put together a little test plan for yourself. What are the things you should double-check before your changes go live?
In particular test anything that you merged with. Make sure there's no console errors, etc. If you find a problem, stop here and go back to the PR phase to fix it up.
Satisfied? Deploy it.
Run the special command to swap ~community with ~community-staging.
(there's a special endpoint for this, ask us about it and sit beside a team member the first time you use it. It's the same thing as renaming the two projects, but it does this atomically and without downtime, which you can't do if you rename them manually.)
Repeat the special command to swap ~community with ~community-staging.
Thereby putting things back the way they were. Now you have time to fix it and try again.
After you revert, check on if any live changes were made to the site after you deployed and before you reverted. (Are the curated items the same on both ~community and ~community-staging?). If so, port the curated updates to the reverted page so that the edits are preserved.
Take a glance at glitch.com and see that your changes are live. (There's a 5 minute cloudfront cache, so you can view community.glitch.me if you need to get around that, or otherwise go to an uncached glitch.com URL to bypass it.)
This is also a fun time to grab a screenshot and share what you've shipped, if you like.
Good job :-) Pop back over to #community and tell the room that you're all done.
Making Live Edits
Can I just edit ~community directly, since it’s Glitch we’re dealing with here?
Sure thing. All standard caveats and cautions apply. This is appropriate for updating the curated content, fixing typos, editing .md files, and one-line bug fixes. Our build scripts don't update the live site until the build is healthy and your changes are complete.