Skip to content

Latest commit

 

History

History
63 lines (52 loc) · 5.27 KB

HowToContribute.md

File metadata and controls

63 lines (52 loc) · 5.27 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 rendered as a front-end website with the URL: https://bssw.io.

After undergoing review for content and formatting, resources in .md files written in GitHub Markdown transition to appear on the front-end website. 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. - event - A workshop, tutorial, conference, or other event with activities related to software productivity and sustainability.
  10. Assign issue to a milestone, if you want to commit to a deadline.
  11. Create your contribution!

Create Your Contribution

The document What To Contribute provides guidance about where to put the file for your new contribution in the BSSw Github repo, depending on the type of content you are creating (article, curated content, event).

Preferred Approach (Simple): Google Form Submission

The BSSw team has a new preferred approach that will work for most submissions (article, blog, curated content or event announcement). This approach simplifies the creation of meta data by providing the author with a guided list of meta data choices. Once the author submits the form, a back end processing tool converts the form submission to the markdown equivalent.

  1. Make sure you review the What To Contribute guidance. While the Google form makes the submission simpler, the author must still be familiar with contribution policies.
  2. Enter information in this Google form.
  3. Notify us of your contribution by contacting us on the bssw.io contact page.

Preferred Approach (Advanced): 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.