-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathcontribute.qmd
161 lines (98 loc) · 7.24 KB
/
contribute.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
---
title: "Contribute"
toc: true
comments: false
lightbox: true
---
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](https://github.com/FRBCesab/tips-and-tricks/blob/main/CONTRIBUTING.md) guide for any other types of contribution (reporting bug, fixing typo, improving published post, etc.).
::: {.callout-warning}
## Code of conduct
This blog is released with a [Contributor Code of Conduct](https://github.com/frbcesab/tips-and-tricks/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
:::
## Workflow
This blog is hosted on [GitHub](https://github.com/frbcesab/tips-and-tricks) and we use the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow)
to collaborate on this project.
Proceed as follow to write and submit your own post:
1. [**Fork**](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) this [repository](https://github.com/frbcesab/tips-and-tricks) using the GitHub interface.
1. [**Clone**](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) your fork by opening RStudio IDE and create a New Project from Version Control.
1. **Set up** and **write** your post (see below [Writing a post](#authoring)).
1. **Stage** (`git add`) and **commit** (`git commit`) your changes.
1. **Push** your changes to your GitHub fork.
1. Submit a [**Pull Request**](https://docs.github.com/en/get-started/quickstart/contributing-to-projects#making-a-pull-request) on the [original repo](https://github.com/frbcesab/tips-and-tricks/compare) (see below [Pull request](#pull-request)).
We will then review your Pull Request as soon as possible.
::: {.callout-important}
## 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.<br/>
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](https://cran.r-project.org/) |
| RStudio Desktop | Integrated development environment (IDE) for R | [link](https://posit.co/download/rstudio-desktop/) |
| Quarto CLI | Scientific publishing system used for this blog | [link](https://quarto.org/) |
| Git | Version control software | [link](https://git-scm.com/) |
<br/>
In addition:
- Install the {{< fa brands r-project >}} packages [`cli`](https://cli.r-lib.org/), [`devtools`](https://devtools.r-lib.org/), and [`gert`](https://docs.ropensci.org/gert/).
- Check your `git` configuration by reading this [dedicated page](https://frbcesab.github.io/rsetup/chapters/git.html).
## Authoring
### Post setup
Run the {{< fa brands r-project >}} command `devtools::load_all()` to load and access [helper functions](https://github.com/FRBCesab/tips-and-tricks/tree/main/R) developed for this blog.
Then create the file structure for your new post. The function [`create_post()`](https://github.com/FRBCesab/tips-and-tricks/blob/main/R/create_post.R) has been developed to make this task easier.
For example,
```{r}
#| eval: false
## 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](https://quarto.org/docs/websites/website-blog.html#posts-directory)) in the post file (`index.qmd` file) as follow:
```yaml
---
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](https://quarto.org/docs/authoring/markdown-basics.html) (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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)).
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:
```sh
## 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).
{.lightbox fig-align="left" width="100%"}
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.
{.lightbox fig-align="left" width="100%"}
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).
{.lightbox fig-align="left" width="100%"}
This will open a new PR and inform the blog maintainers that they can review your PR.
{.lightbox fig-align="left" width="100%"}
Your post will be merged (by the blog maintainer) into the `main` branch and will be accessible a few minutes later [here](https://frbcesab.github.io/tips-and-tricks/).