- Working with your own repository
- Table of contents
It's super helpful to run your own, event-level, GitHub fork of the main repository for devopsdays-web to make changes there, and then push the pull request up to the main repo.
We suggest that you follow the same process that we do for the main repo, which would be as follows:
- Make your changes in a branch. Push that branch up to your repo.
- Submit a pull request in your own repo against your own main. Make sure that the deploy previews from Netlify (this doc will explain later how to set them up) look good!
- If everything looks good to you, merge them into your own main just to make sure that the full build works (for example, in the build to main, Netlify will run various Gulp tasks to retinafy images, minify html, etc. View the tasks in the
gulpdirectory if you're curious). - If everything still looks awesome, submit a PR from your
mainbranch todevopsdays/devopsdays-web.
First, you'll want to set up an organization for your devopsdays event. Go to github.com and under your name, scroll down and click on "Create Organization":
Fill out the form, choosing the free plan. Give the organization a good name that makes sense.
Finally, add team members to your organization. You do not need to do this right away.
Go to the devopsdays/devopsdays-web repository, and click on the "Fork" button in the upper right:
Make sure you choose your new organization as the location to fork it to, not to your own GitHub account:
You should end up with a fork that looks a little like this:
Click on the "Clone or Download" button on your repo. Copy the full URL listed there (ssh or https, depending upon your preference).
At the command line, wherever you want to keep your code, enter the following (inserting the URL you copied instead of $URL):
git clone $URL
You will see output similar to this:
~/src/github.com/mts-devopsdays/ git clone git@github.com:mts-devopsdays/devopsdays-web.git
Cloning into 'devopsdays-web'...
Kryptonite ▶ Requesting SSH authentication from phone
Kryptonite ▶ Success. Request Allowed ✔
remote: Counting objects: 55836, done.
remote: Compressing objects: 100% (147/147), done.
remote: Total 55836 (delta 55), reused 1 (delta 1), pack-reused 55686
Receiving objects: 100% (55836/55836), 148.63 MiB | 4.45 MiB/s, done.
Resolving deltas: 100% (30321/30321), done.
~/src/github.com/mts-devopsdays/
Now, change directories into the new devopsdays-web directory you created. You will want to create an additional remote to the devopsdays-web upstream. Use one of these commands (depending on if you prefer HTTPS or SSH)
git remote add upstream git@github.com:devopsdays/devopsdays-web.git
or
git remote add upstream https://github.com/devopsdays/devopsdays-web.git
If you enter the command git remote -v you will see all your remotes:
~/src/github.com/mts-devopsdays/devopsdays-web/ [main] git remote -v
origin git@github.com:mts-devopsdays/devopsdays-web.git (fetch)
origin git@github.com:mts-devopsdays/devopsdays-web.git (push)
upstream git@github.com:devopsdays/devopsdays-web.git (fetch)
upstream git@github.com:devopsdays/devopsdays-web.git (push)
This is essential because you will need to regularly merge down changes from upstream (devopsdays/devopsdays-web) or your pull requests may be rejected.
Using Netlify will allow for a function called "deploy previews", which allows any changes you make to a branch in your repository (if they have a pull request) to be viewed live, in a browser. Netlify is free for open-source projects, so as long as you haven't made your repository private, it shouldn't cost anything.
Log onto https://www.netlify.com and click on the "Sign Up" button:
Choose to log in with GitHub. Use the same account you've been using (since it needs permissions to your repositories).
You may be prompted to enter your GitHub credentials:
You will then be prompted to authorize Netlify to have access to your GitHub account:
Choose to set up a new site from Git:
Select GitHub as the provider (Note: We recommend you tick the "Limit GitHub access to public repositories" option to ensure you don't provide access to any private repos you may have access to by accident):
Finally, select the repository you wish to use. This is the fork of devopsdays-web you created earlier:
You will be prompted for some build commands. Enter them as follows:
(Note. The build command is hugo_0.19 --theme=devopsdays-theme --buildDrafts=false; don't worry about the hugo version as this is handled in a settings file already in your repository. We have to put in a build command, even though it will be over-ridden.)
Finish up by clicking on "Deploy Site". We aren't done, but this takes us to the next steps.
This is optional, but will make it much easier to track and remember. Click on "Settings", and then change the site name as indicated:
Also an optional step, but it's advised to perform it if your repository is not protected:
When you are ready to make some changes, the first thing to do is make sure you are in the local directory where you cloned down the fork. Before starting any new change, it is essential that you rebase your local repository from the upstream. Issue these commands:
git checkout maingit pull upstream main --rebase
This confirms you are on the main branch locally, and then applies the changes from the upstream to your copy.
The next step is to create a new branch for the changes you are going to make. Use the command git checkout -b my-new-branch (where "my-new-branch" is a recognizable name for the set of changes, such as add-matt-bio). This switches you to a new branch for you to do your work.
After you have saved your work, you will need to add it to the staging area with git. You can either do this one file at a time (git add data/events/2017-chicago.yml) or add all changed files with git add . To see the list of files changed, type in git status
~/src/github.com/mts-devopsdays/devopsdays-web/ [add-matt-bio*] git status
On branch add-matt-bio
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: data/events/2017-chicago.yml
no changes added to commit (use "git add" and/or "git commit -a")
Now that we have staged the files, we need to commit them. Use the command git commit with the -m flag to add a useful message. The workflow looks something like this:
~/src/github.com/mts-devopsdays/devopsdays-web/ [add-matt-bio*] git add .
~/src/github.com/mts-devopsdays/devopsdays-web/ [add-matt-bio+] git status
On branch add-matt-bio
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
modified: data/events/2017-chicago.yml
~/src/github.com/mts-devopsdays/devopsdays-web/ [add-matt-bio+] git commit -m "Add Matt Stratton bio to Chicago"
[add-matt-bio 0ea02bc2] Add Matt Stratton bio to Chicago
1 file changed, 1 insertion(+), 1 deletion(-)
~/src/github.com/mts-devopsdays/devopsdays-web/ [add-matt-bio] git status
On branch add-matt-bio
nothing to commit, working tree clean
You now need to push up your branch to your own origin (your fork). Do this with the command git push origin name-of-your-branch, i.e.
~/src/github.com/mts-devopsdays/devopsdays-web/ [add-matt-bio] git push origin add-matt-bio
Counting objects: 1131, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (542/542), done.
Writing objects: 100% (1131/1131), 13.56 MiB | 2.73 MiB/s, done.
Total 1131 (delta 685), reused 995 (delta 568)
remote: Resolving deltas: 100% (685/685), completed with 151 local objects.
To github.com:mts-devopsdays/devopsdays-web.git
* [new branch] add-matt-bio -> add-matt-bio
Now that you have pushed up your branch to your fork, you need to submit it as a pull request to your own main branch on your fork. This allows your other teammates to approve/view the changes you have proposed.
Open the URL of your fork in a browser (make sure you are logged into GitHub). You should see something like this:
Make sure you have changed the base fork to your own main branch. It should look like this.
Now you can review the pull request, and add any comments that make sense.
You can easily see the status and discussion on a PR by clicking on its name in the list of Pull Requests:
If you see a passed indicator for Netlify, click on "Details" to see the preview of the site with your changes.
Once you are satisfied with the pull request, click the "Merge pull request" button, and you are good to go.
Now, visit https://github.com/devopsdays/devopsdays-web/pulls and click on "New pull requests"
Click "compare across forks"
When filling out the pull request form, make sure that you follow the guidelines in the template - including replacing the template text itself! Also, if you tick the "Allow edits from maintainers" box, that will help the maintainers directly fix any issues with your PR.
That's it! Now you can either view the proposed merge via Netlify (using a similar technique as before), or wait for your change to be merged. Be advised that maintainers may have questions about your PR, so watch for the conversation thread.
Bear in mind that in order for your PR to be merged, you need to be one of the listed organizers for a given event, and we'll only merge your PRs regarding that event.