Skip to content

Latest commit

 

History

History
53 lines (45 loc) · 4.32 KB

HowToContribute.md

File metadata and controls

53 lines (45 loc) · 4.32 KB
Raw

How to Contribute Content to Better Scientific Software

Background

The repository https://github.com/betterscientificsoftware/betterscientificsoftware.github.io is a specially-designated repository according to GitHub organizational policy. The contents of this repository are automatically rendered as a website with the URL: https://betterscientificsoftware.github.io/. For example this file (HowToContribute.md) is automatically rendered at the URL https://betterscientificsoftware.github.io/HowToContribute.html

Any .md file written in GitHub Markdown is automatically visible via its pre-defined URL. Given the ease of content development using GitHub's online content capabilities, the ability to work with the website as a GitHub repository, and the possibility to create scripting tools that can extract, create and test content in this repository, we encourage contributors to the BSSW project to use the following processes.

Before creating your content

  1. Is your content a good fit? If you have doubts, please see What To Contribute. If you are still unsure, contact the BSSW team.
  2. Ready to contribute? Please set up a GitHub Issue (New to GitHub Issues? See this intro):
  3. Go to the BSSW GitHub Issues page.
  4. Tap on green New issue button.
  5. Enter a descriptive title and a longer comment about the work you will do.
  6. (BSSW non-members) Wait for confirmation from the BSSW team that your proposed contribution is a good fit. Once this is confirmed, continue to Create Your Contribution.
  7. (BSSW members)
  8. If you have site permissions, you can assign the issue to yourself or someone else.
  9. Assign appropriate labels. Common choices are: - blog - Tell us what is on your mind about Better Scientific Software. Keep it short and to the point. - curated link - Did you find an article you want to share with the BSSW community? Describe it and include a link. - howto - Did you write instructions for how to accomplish a useful task? Write a How To. - short article - Like a blog, but more fact than experience. - whatis - A What Is describes terms and concepts, especially useful as background for a How To.
  10. Assign issue to a milestone, if you want to commit to a deadline.
  11. Create your contribution!

Create Your Contribution

Preferred Approach: Web based

  1. Open a browser window pointed at the Better Scientific Software GitHub site.
  2. Find an existing article that is similar in type.
  • View the article in Raw mode.
  • Copy article text including the comment containing the metadata.
  1. Select Create New File or open an existing file.
  2. Paste text from existing article into your new document, as a starting point.
  3. Edit using GitHub Markdown.
  4. Select Commit New File at the bottom of the page.
  • If you have permission, you can commit directly to master.
  • If not, you can create a branch and submit a pull-request (follow instructions).

Alternative: Clone/Fork repository locally

  1. Clone (if you are a BSSW member) or fork the repository.
  2. Create a new .md file in your local repository, or edit an existing file.
  3. Add the file to the repo (if new) or commit the updated file to your local repository.
  4. Push the change, or create a pull request, to send the file to the main GitHub repository
  5. If you submitted a pull request, it will be reviewed by BSSW team members for inclusion in the repository. Note: If you are not familiar with GitHub workflows, there are many tutorials to help.

Style Guide

See the BSSW Style Guide for guidance on naming conventions, descriptive text, and metadata.