Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update contributing guide for blog post #354

Merged
merged 1 commit into from
Jan 20, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 60 additions & 34 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
This website is using [quarto](https://quarto.org/)
and the HTML output is automatically generated on pushes to `main`
and the HTML output is automatically generated on pushes to `main`
via the [`quarto-publish.yml` GitHub Actions workflow](https://github.com/epiverse-trace/epiverse-trace.github.io/blob/main/.github/workflows/quarto-publish.yml).

All contributions should add an ORCiD for each author.
Expand All @@ -8,7 +8,7 @@ All contributions should add an ORCiD for each author.

### Linting

The validity and best usage of quarto syntax is enforced by the use of a [markdown linter as part of our continuous integration](https://github.com/epiverse-trace/.github/blob/main/workflows/lint-changed-quarto.yaml).
The validity and best usage of quarto syntax is enforced by the use of a [markdown linter as part of our continuous integration](https://github.com/epiverse-trace/.github/blob/main/workflows/lint-changed-quarto.yaml).
You can reproduce the continuous integration checks locally by running in your terminal:

```sh
Expand All @@ -18,29 +18,36 @@ npx markdownlint-cli . --dot --disable line_length first-line-h1 link-image-refe

### Pure quarto/markdown syntax

Whenever possible, you should prefer direct markdown/quarto syntax rather than HTML or R code.
Indeed, using HTML constrains us into outputting to a specific format,
while the strength or markdown is to be able to output in many formats.
Using R code adds a dependency to R (and possible some R packages such as knitr) which is not necessary.
Whenever possible, you should prefer direct markdown/quarto syntax rather than HTML or R code.
Indeed, using HTML constrains us into outputting to a specific format,
while the strength or markdown is to be able to output in many formats.
Using R code adds a dependency to R (and possible some R packages such as knitr) which is not necessary.
Below are some examples of good vs bad practices:

- Insert a link (this specific example is checked by our linter):
- BAD

```html
<a href="https://www.example.com/">my link</a>
```

- GOOD

```md
[my link](https://www.example.com)
```

- Insert an image:
- BAD

````r
```
knitr::include_graphics("my_img.png")
```
````

- GOOD

```md
![my img](my_img.png)
```
Expand All @@ -52,52 +59,55 @@ This makes it easier to detect changes with git.

## Contributing a new blog post

The Epiverse-TRACE blog is a rather informal space for us to collectively share learnings and document events in the community. For example, we share practical information around development, code, and process.

As a rule of thumb: If you find it interesting to share, it most likely is.

### Before starting to write

The first step before starting to write a blog post is to open an issue in this repository
so that others can weigh in on your ideas, propose additional directions, and possibly volunteer to collaborate with you.
Once this issue is opened, please tag it with [`future post`](https://github.com/epiverse-trace/epiverse-trace.github.io/issues?q=is%3Aissue+label%3A%22future+post%22)
and share it in the `#dev-general` slack channel.
You can [start a discussion](https://github.com/orgs/epiverse-trace/discussions/new?category=blog-post-ideas) if you have a blog idea you want more input on.
This way, others can weigh in on your ideas, propose additional directions, and possibly volunteer to collaborate with you.
The discussion will be automatically cross-posted to the `#github-discussions` channel on Slack.

### General guidance for writing blog posts

#### Scope

Try to keep your post focused concise and focus in a single issue.
If you feel your post is getting too long,
it is often a good idea to split it into several smaller posts linking back to one another.
Try to keep your post focused concise and focus in a single issue.
If you feel your post is getting too long,
it is often a good idea to split it into several smaller posts linking back to one another.
This often gets more views.

The aforementioned `future post` issue can help you to define the exact scope of your post.

#### Posts as one part of the ecosystem
#### Posts as one part of the ecosystem

Blog posts should as much as possible be self-contained.
I.e., they should make sense on their own
Blog posts should as much as possible be self-contained.
I.e., they should make sense on their own
and not require users to go read a lot of external links to understand your point.

However, our blog doesn't live in isolation from the rest of the community
and it is good practice to link back to other posts and other resources as much as possible.
If someone else already wrote on the topic you're treating or an adjacent topic, or if there are resources to go deeper in this topic,
you should most definitely link them back.
Practically speaking, there is no upper limit on the number of external links you can add.
However, our blog doesn't live in isolation from the rest of the community
and it is good practice to link back to other posts and other resources as much as possible.
If someone else already wrote on the topic you're treating or an adjacent topic, or if there are resources to go deeper in this topic,
you should most definitely link them back.
Practically speaking, there is no upper limit on the number of external links you can add.
The more the better.

When you mention other resources and the position of your post in the existing documentation ecosystem,
make sure your phrasing couldn't be taken as dismissive or disparaging.
Our posts aim at building up on others' work and lifting up other members of the community.
When you mention other resources and the position of your post in the existing documentation ecosystem,
make sure your phrasing couldn't be taken as dismissive or disparaging.
Our posts aim at building up on others' work and lifting up other members of the community.

This is in line with our [community values](https://data.org/news/epiverse-trace-a-values-based-approach-to-open-source-ecosystems/),
This is in line with our [community values](https://data.org/news/epiverse-trace-a-values-based-approach-to-open-source-ecosystems/),
where we committed to **reciprocity**.

#### Tone and language

We don't require a formal tone in posts.
We don't require a formal tone in posts.
Feel free to adopt everyday vocabulary.

You should however ensure that your posts are always respectful of everybody's work,
and everybody's experience, as describe in our Code of Conduct.
In particular, we are paying extra attention to avoid dismissive or demotivating language, such as "obvious", "just", "straightforward", etc.
and everybody's experience, as describe in our Code of Conduct.
In particular, we are paying extra attention to avoid dismissive or demotivating language, such as "obvious", "just", "straightforward", etc.
The "alex" GitHub Actions workflow can help you detect and fix such occurrences of demotivating language.

#### Step by step
Expand All @@ -114,16 +124,28 @@ To make contributing a blog post accessible, we outline an exact step by step gu

If you want to get a DOI for your blog post, please add the `DOI` category (case sensitive).

#### Scheduled posts

We support publishing a blog at a specific date using a [Merge Schedule](https://github.com/gr2m/merge-schedule-action). To enable a scheduled post, please add the following to the original post in the pull request:

```md
/schedule YYYY-MM-DDTHH:MM:SS

/schedule 2025-01-01T08:00
```

The [scheduling functions on UTC time](https://www.timeanddate.com/worldclock/timezone/utc).

### After the post is published

Once your post is published, we already have some systems in place to try and advertise it in the community:

- it is automatically shared on [R-bloggers](https://www.r-bloggers.com/)
- it is automatically shared on [R-weekly](https://rweekly.org/),
which can often result in it also being discussed in the [R-weekly podcast](https://rweekly.fireside.fm/).
- it is automatically shared on [R-weekly](https://rweekly.org/),
which can often result in it also being discussed in the [R-weekly podcast](https://rweekly.fireside.fm/).
Keep an eye on their social media account to see if your post is mentioned: [twitter](https://twitter.com/theRcast)

You should also get in touch with the current week's curator of our [Epiverse-TRACE twitter account](https://twitter.com/Epiverse_TRACE/),
You should also get in touch with the current week's curator of our [Epiverse-TRACE twitter account](https://twitter.com/Epiverse_TRACE/),
possibly with a short summary of your post they can use.

If you added the DOI category, you can find the DOI using [our Rogue Scholar index](https://rogue-scholar.org/blogs/epiverse_trace). You can add the DOI as metadata to your post by adding `doi: '<doi>'` to your post metadata (see [an example here](https://github.com/epiverse-trace/epiverse-trace.github.io/blob/e63c51b406409eb5e1bf9fc9201606793c3dd7d4/posts/parent-class/index.qmd#L7C1-L8C1).
Expand All @@ -136,25 +158,29 @@ Alongside the pdf of your slides, please add an `index.qmd` with the following r
- Schedule if the event includes multiple presenters and/or multiple presentations
- The slides in an iframe:
- For slides in 16:9 format:

````
```{=html}
<iframe width="780" height="438.75" src="slides.pdf" title="slides from event"></iframe>
```
````

- For slides in 4:3 format:

````
```{=html}
<iframe width="780" height="500" src="slides.pdf" title="slides from event"></iframe>
```
````
- A list of questions asked during the presentation and a short answer,

- A list of questions asked during the presentation and a short answer,
especially if you didn't have time to answer all questions live
- A link to the recording if available

## Adding new packages to the hexwall

Packages on the hexwall are automatically pulled from the list in
Packages on the hexwall are automatically pulled from the list in
`_data/epiverse_pkgs.csv`. New packages can be added by submitting a PR editing
this file.
The package logos are fetched from
The package logos are fetched from
<https://github.com/epiverse-trace/hex-stickers>.
Loading