Skip to content

Latest commit

 

History

History
134 lines (90 loc) · 10.9 KB

Contributing.md

File metadata and controls

134 lines (90 loc) · 10.9 KB
Raw

Contributing to the MERL Center public repo

Sections

Background | Licenses | Types of MERL Center content | For MERL Center Members | Contact

Background

The MERL Center is an interdisciplinary community that is creating resources for monitoring, evaluation, research and learning (MERL) practitioners to understand if, how, and when to use open source solutions. The MERL Center is a part of the larger MERL Tech community and is organized and funded by GitHub's Social Impact, Tech for Social Good team. You can read more about the MERL Center here.

This is the public repository of the MERL Center on which learning content and the website code for the MERL Center website are hosted. MERL Center members collaborate on the MERL Tech GitHub organization (account) through two repos(itories) - this public repo and a repo that is only for members. Anyone who wants to propose and contribute a new piece of learning content must go through a basic onboarding process and become a MERL Center member. Becoming a MERL Center member is free and quick, though we ask MERL Center members have at least one year of professional experience related to MERL and/or open source. Currently, only MERL Center members can propose changes to content. This may change in the future to allow anyone to propose changes. Anyone with access to GitHub has read-only access to everything on this repo.

Join the MERL Center

If you'd like to become a MERL Center member, please fill out this form. We ask you have at least one year of professional experience related to MERL and/or open source.

MERL Center Website

Content found on this repo can also be found at https://merlcenter.org.

Licenses

Back to top

Types of MERL Center content

Learning Content

Learning content currently refers to case studies or guides found at https://merlcenter.org

  • Text - text that is exclusively or primarily for a case study or a guide
  • Images - charts, graphs, screenshots, photos that are exclusively or primarily for a case study or a guide
  • Code - code that is exclusively or primarily part of a case study or a guide

Web Code

Back to top

For MERL Center Members

Create a New Piece of Learning Content

You need the correct permissions level (access) to follow the steps below. Contact [email protected] if you're a MERL Center member without access. Your piece of content must have completed these steps before being submitted to this repo. Note that file is only visible to MERL Center members.

Here's a markdown formatting guide

The following steps are for the browser version of GitHub:

  1. Click on the Code tab at the top of the screen
  2. Click on the _guides or _caseStudies sub-directory (folder), depending on the type of content you're submitting
  3. At the top right, click the Add file button, then Create new file if you don't already have a markdown file created. Click Upload file if you do already have a markdown file created.
  4. Add your title of your file in the following format: YYYY-MM-DD-this-is-my-title.md. A real example is 2021-04-23-Dispelling-myths-qualifying-assumptions.md, which appears on the website at https://merlcenter.org/guides/Dispelling-myths-qualifying-assumptions
  5. Add your frontmatter, which is the information that needs to appear at the top, to the file. Click the pencil icon on this file

Screen Shot 2021-08-24 at 1 44 36 PM

and copy the text highlighted below in blue into your post. Screen Shot 2021-08-24 at 1 44 58 PM

  1. Below the dotted line, add the body of your content that is formatted in markdown. Here's a markdown cheat sheet to help you format.
  2. Click the Commit changes button to submit your file. This will open a pull request and automatically assign the CodeOwners team (Editors team) to review and merge your pull request.
  3. Someone from the CodeOwners team (Editors team) may request you make changes before they merge your pull request. To do so, click on the Pull requests tab at the top, click on your pull request, then click on the three dots by your file to edit directly. Once you edit, you'll have two options in the Commit changes dialogue: push those changes to the same pull request or create another branch, which you can think of as a pull request to a pull request.

Screen Shot 2021-08-24 at 11 58 58 AM

  1. After your pull request has been merged, your content will be live on the repo immediately and on the MERL Center website shortly.

Edit an Existing Piece of Learning Content

  1. Navigate to the piece of learning content you wish to edit by following the first two steps above
  2. Click the pencil icon indicated below

Screen Shot 2021-08-24 at 11 00 36 AM

  1. Make your changes and click the Commit changes button. This will open a pull request and automatically assign the CodeOwners team (Editors team) to review. You can also assign a specific individual you want to review your changes, such as the author of the original post.
  2. After your pull request has been merged, your content will be live on the repo immediately and on the MERL Center website shortly. The CodeOwner (editor) may request changes before merging.

Formatting Options for Learning Content

  • One or more authors
  • One or more tags
  • Featured image or no featured image

Formatting Images for Learning Content

  1. Featured images will appear as the learning content piece thumbnail
  2. The aspect ratio of featured images will be retained
  3. Larger photos (more than 1000 x 1000 px) may appear blurry
  4. If there is no featured image listed, the default MERL Center logo will appear on the website as the thumbnail
  5. Use a descriptive title for your image using lowercase (no caps) and no spaces. Use -dashes- if you need to separate words in the image file name. Example: this-is-my-image-file.png

Adding Images to Your Learning Content

  1. Click on the Code tab at the top of the screen
  2. Click on assets, img, posts
  3. Drag your picture in OR at the top, click on Add file and then Upload files. Upload your file and click Commit changes
  4. To add a feature image, copy and paste the name of your image file in the featuredImage: field. For example:

featuredImage: building-open-source-conceptual-model1.png

  1. To add an image in the body of your learning content, use this - ![Description of your image](/assets/img/posts/name-of-your-image-file.png) - where the part after /posts is the name of your image file.

CodeOwners

Note that despite CodeOwners containing the word "code", the MERL Center uses CodeOwners to review and merge pull requests on text files.

CodeOwners are automatically assigned to pull requests (proposed changes) made to files in a particular sub-directory (folder). This removes the guess work on who should edit a piece of learning content. You can read about CodeOwners generally here and view the MERL Center CodeOwners file here. Contact [email protected] if you want to be added to the CodeOwners (Editors) team.

Permissions Levels*

Types of Contributions Non-MERL Center Members MERL Center Writer MERL Center Editor** MERL Center Admin GitHub Teams Names
Read-only Learning Content X X X X Anyone with access to GitHub
Propose Learning Content changes through pull requests -- X X X merl-center-lc-writers, merl-center-lc-editors, merl-center-public-admins
Approve and merge Learning Content changes -- -- X X merl-center-lc-editors, merl-center-public-admins
Read-only Web Code X X X X Anyone with access to GitHub
Propose (limited) Web Code changes through pull requests -- X X X merl-center-public-admins
Approve and merge (limited) Web Code changes -- -- -- X merl-center-public-admins
Change Repo settings -- -- -- X merl-center-public-admins
  • Permissions levels are a work-in-progress and should be fully implemented by October 2021
  • MERL Center Editors are the same as the CodeOwners teams (see above)

Things MERL Center Members can do to Modify the Website

Only admins are allowed to make most changes to the MERL Center website. Below is a list of things any MERL Center writer or editor can do.

Add tags

  1. Consult with the MERL Center admins to propose a tag
  2. Go to https://github.com/MERLTech/MERL-Center-public/blob/main/_data/tags.yml
  3. Follow the steps above to make a pull request and add your tag

more coming

Back to top

Contact

Email [email protected] with feedback or questions, or open an issue.

Back to top