Update April 2022:
We have moved to WordPress so this article has become outdated. If you want to become a guest author for Pybites join our Slack and let’s chat there …
Hello Everybody! In this article I’ll run through the procedure of using git and github to submit a guest article to PyBites.
1. Forking the Repository
In order to get started, you have to create a fork of the original repository.
A fork is a copy of a project to your own Github account.
This way, you can work on your own copy and ask the project maintainer to accept some modifications on your copy into the main repository.
Head over to the PyBites blog Github repo and look for the Fork icon in the top right, I’ve marked it in green:
Git will start creating the copy, and when it’s done, you’ll have your very own pybites.github.io-src fork!
2. Cloning your copy
Now that we have our running fork, we can clone this from our own Github account.
A clone is a local copy of a project from your Github to your local machine, where you can start editing!
3. Preparing for the future
While you are making your edits or adding your article, the maintainers, or other contributors may be doing the same!
Git already knows of our origin, it knows where we cloned from.
We also need to tell it what our upstream is, where did we fork from? Which is where the maintainers will be adding updates.
In this case that’s https://github.com/pybites/pybites.github.io-src
So now, if we want to get the maintainers latest modifications and add them to our own repository, we can first pull the upstream master branch, and then push it to our origin master branch!
4. Before making modifications
The Gittiquette says that you should make a branch before starting any modifications.
A branch is a copy of our local copy at a certain point in time that will go on to live it’s on life, and eventually (hopefully) rejoin with it’s master somewhere down the road.
You can either create a branch while checking it out, or you can create a branch, and later switch to it with checkout.
You might want to set your branch name to something that you can recognize. Some trees have a lot of branches!
I’m currently writing this “how to add guest articles”, so I’ll give mine an obvious name:
Branching is mainly important when you want to verify that your new modifications are not conflicting with any new changes in the upstream.
5. Writing your article
Post directory and style
Guest articles are stored in content, are written in markdown and usually start with guest-
I’ve added a template you can use here
It contains the structure of most articles and some basic markdown syntax as example, [here]’s another cheat sheet for if you want to do even more!
You can also look at the other articles as an example.
Adding images
If you have images you want to add (screenshots, infographics,…), you can add them under content/images/ and refer to them in your article like this:
A new guest!
If this is your first article, you should also add a small bio in content/pages/guests.md, right above the comment:
You can copy one from the guests file yourself, or use the template for the bio.
6. Adding and commiting your changes
Commit’s are collections of small changes you have made. Adding your article could probably go in a single commit.
You’re going to tell git that you’ve changed or added a bunch of files first:
…and then you’re gonna store these changes in a commit:
I still have some work to do, but when you’re ready, you can push your modified branch back to the branch on it’s origin you’ve created for the modifications:
And you’re all set!
If you’re logged in and you go to the upstream github page, you’ll notice github automatically detects you’ve pushed a branch that was related to this project!
And you can create a pull request, which effectively asks the maintainer to pull the changes you’ve made into the master branch.
Now all you have to do is wait for someone to review your changes and if they are approved, your article will soon be ours to read on the PyBites blog!
—
Thanks for reading, I hope you enjoyed it as much as I enjoyed writing it.
If you have any remarks or questions, you can likely find me on the Pybites Slack Channel as ‘Jarvis’.
Keep calm and code in Python!
— Cedric