Skip to content

Add CONTRIBUTING.md for posts and pages #7

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

Merged
merged 6 commits into from
Jun 18, 2021
Merged
Changes from 2 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
42 changes: 42 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Contributing
We welcome contributions from people working on research software around Culham.

This guide summarises the [Github guide](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/adding-content-to-your-github-pages-site-using-jekyll) for adding new content to a Jekyll site. The "publishing source" is the `master` branch; anything added to `master` will be published automatically. Firstly, please create an issue and branch for the content you wish to add.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should expand on "create an issue and branch".

Perhaps, "create an issue which explains briefly what you are planning to add (and can be used for discussion)".

Do we want people to work on forks? I think probably not, in which case should we say something about how to request access?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure. How about using the issue for discussion of the topic and ideas, then the PR for discussion of the actual content?

I'm ashamed to say I don't know what we should do about people requesting access. Is there any way you can do this through github, or is it a case of them sending me an email and then me adding them? This is my first time dealing with an "organisation" account too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've just clarified the contributing guidance; I hope that's about right now.

It looks like users need to be added to an organisation; they can't request access through github. Perhaps we should provide a contact email for this. Personal or UKAEA?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use UKAEA email.


There are two main types of content, pages and posts, both written in Markdown. A page is permanent, without an associated date, whereas a post has a date associated with it.

## Adding a blog post
In the `_posts` directory, create a new Markdown file of the form `YYYY-MM-DD-NAME-OF-POST.md` (it's easiest to copy and edit the `_posts/2021-03-15-welcome-to-jekyll.md` file). Then add the YAML front matter:
```yaml
---
layout: post
title: "POST TITLE"
date: YYYY-MM-DD hh:mm:ss -0000
categories: CATEGORY-1 CATEGORY-2
---
```

Below this, add the Markdown content for your post.

## Adding a page
In the project root directory, create a new file in the form `PAGE-NAME.md` (or copy and edit the `about.md` file). Then add the YAML front matter:
```yaml
---
layout: page
title: "PAGE TITLE"
permalink: /URL-PATH/
---
```

Below this, add the Markdown content for your post.

## Previewing changes
Once you've set up Jekyll locally (see the `README.md`), you can preview your changes using:
```
bundle exec jekyll serve
```

and navigating to http://localhost:4000.

## Publishing
Open a pull request for the changes on your branch. Once merged to `master`, the content will be published on [researchsoftwareculham.github.io](https://researchsoftwareculham.github.io/), which is public.
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,5 @@
# ResearchSoftwareCulham.github.io
A blog for Research Software at Culham.

## Contributing a blog post or page
Please see the `CONTRIBUTING.md` for guidance on adding content.