Contribute

First off, thanks for taking the time to contribute to tips-and-tricks! All types of contributions are encouraged and valued.

If you want to contribute by writing your own post, this page is for you. Read the CONTRIBUTING.md guide for any other types of contribution (reporting bug, fixing typo, improving published post, etc.).

Code of conduct

This blog is released with a Contributor Code of Conduct. By participating, you are expected to uphold this code.

Workflow

This blog is hosted on GitHub and we use the GitHub flow to collaborate on this project.

Proceed as follow to write and submit your own post:

  1. Fork this repository using the GitHub interface.
  2. Clone your fork by opening RStudio IDE and create a New Project from Version Control.
  3. Set up and write your post (see below Writing a post).
  4. Stage (git add) and commit (git commit) your changes.
  5. Push your changes to your GitHub fork.
  6. Submit a Pull Request on the original repo (see below Pull request).

We will then review your Pull Request as soon as possible.

Branch naming rule

For each post, a new git branch will be created automatically and named as follow (in lower case): yyyy-mm-dd-title-of-the-post. This will make easier the review process and the maintenance of this blog.
For example: 2024-05-07-working-with-git-branches.

Requirements

Here is a list of the software required to contribute to this blog:

Software Description Website
R The R environment link
RStudio Desktop Integrated development environment (IDE) for R link
Quarto CLI Scientific publishing system used for this blog link
Git Version control software link


In addition:

Authoring

Post setup

Run the command devtools::load_all() to load and access helper functions developed for this blog.

Then create the file structure for your new post. The function create_post() has been developed to make this task easier.

For example,

## Create a new post ----
create_post(title = "Working with git branches", 
            date  = "2024-05-07")

N.B. You can omit the argument date if you want to use the today date.

This function will:

  • create a new git branch named 2024-05-07-working-with-git-branches
  • switch the repo to this new git branch
  • create a subfolder in posts/ named 2024-05-07-working-with-git-branches
  • create a Quarto file in this subfolder named index.qmd

You will write the content of your post inside this index.qmd file and add additional files (images, data, etc.) in the subfolder posts/2024-05-07-working-with-git-branches/.

Post metadata

Before starting writing your post, please edit the post metadata (i.e. the YAML section) in the post file (index.qmd file) as follow:

---
title: "Working with git branches"
author: "Nicolas Casajus"
date: "2024-05-07"
categories: [git, git-branch, git-checkout, git-merge]
toc: true
draft: false
lightbox: true
code-overflow: scroll
---
  • Add your name in the author field.
  • Add 3 to 5 tags in the categories field. They will be used to feed to search engine.

Post content

This blog uses the Markdown syntax (Pandoc flavor). By running in the terminal the Quarto command quarto preview, you will start a live server to preview your post as you type.

Pull request

A Pull request is a proposal to merge a set of changes from one branch into another (GitHub documentation).

To submit your new post, you will create a Pull request (PR) to merge the branch 2024-05-07-working-with-git-branches of your fork into the branch main of the original repo.

First, send your local changes to your GitHub fork. On a terminal, run the following command to push your new branch:

## Send your new branch to GitHub (fork) ----
git push --set-upstream origin 2024-05-07-working-with-git-branches

Then create a new PR by visiting your GitHub fork homepage: you should see a new green button named Compare & Pull request (Fig. 1).

Figure 1. Create a Pull request from a Fork

Figure 1. Create a Pull request from a Fork

Add some information about your PR (Fig. 2):

  • Check that you have selected the appropriate repos and branches (A).
  • Add a title (B).
  • Add a description (C). You can link this PR to an existing Issue.

Figure 2. Draft a Pull request

Figure 2. Draft a Pull request

Create a Draft Pull request (D): this will allow you to keep working on your post (i.e. adding commits). All new commits on the branch 2024-05-07-working-with-git-branches will be automatically added to this PR.

Once your post is ready, click on Ready for review to finalize your PR (Fig. 3).

Figure 3. Create a Pull request

Figure 3. Create a Pull request

This will open a new PR and inform the blog maintainers that they can review your PR.

Figure 4. Pull request ready for review

Figure 4. Pull request ready for review

Your post will be merged (by the blog maintainer) into the main branch and will be accessible a few minutes later here.