You've probably heard of GitHub, which hosts millions of coding projects that you can use or learn from.
In this tutorial, we'll see how to:
We'll use a basic Flask
hello world app for the demonstrations. You can use this same project to follow along, or pick any other project on GitHub that interests you.
We'll use the Flask application available at https://github.com/ritza-co/flask-hello-world for demonstration purposes. To import it into Repl.it, press the
+ new repl button, switch to the "Import From GitHub" tab, and paste in the GitHub URL, as shown below.
Press the green
Import from GitHub button and you'll see Repl.it clone the repository and turn it into a repl. In all of our previous projects, we used the
main.py file that Repl.it automatically creates for all new Python projects, and which it runs automatically when you press the
run button. Note how in this GitHub project, we have no
main.py file, and our code is instead in
mydemoapp.py. Therefore, Repl.it will need some help from you to define how to run the project. This is configured through another special file named
.replit. Because there was no
main.py file, Repl.it automatically created this file and will prompt you to configure it.
Select the language (Python) from the first dropdown and type
python mydemoapp.py in the "configure the run button" input. Every time you press the
run button, Repl.it will execute the command given here. If you prefer, you can also edit the
.replit file directly. If you click on it, you'll see it now contains the following configuration, which matches what we provided through the GUI panel.
language = "python3" run = "python mydemoapp.py"
If you hit the
run button, you should see the app start. As you can see, the web application is very basic: all it can do is display a welcome message. If the configuration panel doesn't pop up automatically, you can manually create a file called
.replit and add the configuration above to get the same result.
Some GitHub projects are very large and complicated, and you might not be able to run everything you need directly on Repl.it, but in many cases it just works. Open-source projects can be read and run by anyone, but still have restrictions on who can push changes to them. Next we'll improve this project and request that the owner merges our changes into the original.
Repl.it includes a version control tab which shows you information about the GitHub repository and in some cases allows you to push your changes made in Repl.it back to GitHub.
If you select this version control tab from the menu on the left, you'll see a summary of the linked repository. Note that it's already figured out what changes we've made, and it shows that the
.replit file is new. It would be nice for other people who use this repository with GitHub to have the file automatically, so we might want to push the changes we made back to GitHub.
Note that the owner of the repository is
ritza-co though, so you won't have write permissions for this repository. If you press the
commit & push button, you'll see an error as shown below.
Usually when contributing to open-source projects, you'll first create a "fork" of the original project. This means that you make your own version of the project and, as it's yours, you can make any changes to it that you want. If you think these changes would be useful to others too and are an obvious improvement over the original project, you can make a "pull request", which asks the owner of the original project to merge your changes into the main canonical project.
Create an account on github.com or log in to your existing one and navigate back to the original project (https://github.com/ritza-co/flask-hello-world). In the top right corner, press the
Fork button to create a copy of the project in your own GitHub account.
You should be taken to a new page in GitHub that looks very similar to the old one but which is owned by your own GitHub username. My GitHub username is
sixhobbits so the new URL for me is https://github.com/sixhobbits/flask-hello-world (but yours will be different).
Now, instead of cloning the original project into Repl.it, create a new repl and import this fork of the project instead. Instead of going through the import UI again, you can also just create and load the relevant import URL. These URLs are in the format
https://repl.it/github/<githubproject> so in my case I open https://repl.it/github/sixhobbits/flask-hello-world in my browser (you need to substitute your own GitHub username for this to work).
.replit file again and open the version control tab, as before. Under "what did you change" enter "add .repl file" or a similar message to describe what contributions you're making, and press
commit and push.
You'll see the error again and be presented with the option to connect your Repl.it account to GitHub to prove that you authorise Repl.it to make these changes to GitHub on your behalf.
You can give Repl.it access to all of your repositories (useful if you want to use this integration a lot), but by default it will only get permission for the specific repository that we're working with.
Press the green
approve button and you'll be directed back to Repl.it. Press the
commit & push button again on Repl.it and this time everything should work without any errors.
Navigate back to your fork of the GitHub project, and you should see that the changes are reflected in GitHub too.
As you can see, the new
.replit file is visible and GitHub prompts you to make a pull request back into the original repository. Press
create pull request, add a comment explaining why your changes should be merged into the original repository, and click
Create pull request again.
The owner of the repository will get a notification about your proposal and can choose to add your changes or reject them (in this case, don't be too hopeful about your changes being accepted as the
.replit file being missing is important to follow along the earlier steps of this tutorial 😉.)
For this tutorial, it's important that you do the steps yourself so that everything is correctly linked to your own GitHub account, but if you want an example to play with, use the one below. It's the same as the Flask app but it can greet individual users dynamically instead of having a static welcome message.
Visit https://cwr-06-github--garethdwyer1.repl.co/Gareth to see it in action (replace the last part of the URL with your own name to receive a personalised greeting).
Can you figure out how it works?
Cloning repositories and being able to immediately run them is useful in many scenarios, from just wanting to try out a cool project that you found to running production workflows.
Open-source software only exists because of people who build, maintain, and improve it. There's no global committee that decides who gets to be an open-source software developer and you can be one too. Find a project that you like, look at the "Issues" tab on GitHub to see what problems exist, and try to fix one. Many issues on GitHub are tagged with "Good first issue" to help direct newer developers to places where they can get started.
In the next tutorial, we'll do something a bit different and build a 2D game using PyGame.