Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
378 lines (284 loc) · 13.2 KB

CONTRIBUTING.md

File metadata and controls

378 lines (284 loc) · 13.2 KB

Contributing to ReSA website

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The following is a set of guidelines for contributing to the ReSA website, which is hosted in the ReSA Organization on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

This guide is inspired from Atom's contributing guidelines.

How Can I Contribute?

Reporting Bugs

This section guides you through submitting a bug report for Research Software Alliance. Following these guidelines helps maintainers understand your report 📝, reproduce the behavior 💻 💻, and find related reports 🔎.

Before creating bug reports, please check this list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

Before Submitting A Bug Report

  • Perform a cursory search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. To report a bug, create an issue in the website repository by filling in the bug report template.

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps to reproduce the problem n as many details as possible. For example: which command do you use in the terminal or in GitHub browser. Explain how you did different steps, in addition to what you did. For example: if you moved your cursor to next line, please mention if you used the mouse, or a keyboard button or a programming command in an IDE or GitHub browser.
  • Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/paste text or code.
  • Describe the behavior you observed after following the steps and point out the exact problem in that behaviour/output.
  • Explain what behaviour you expected to see instead and why.
  • Include screenshots or animated GIF/video which show how you followed the steps and clearly demonstrate the problem in the output you observe.

Provide more context by answering the following questions:

  • Can you reproduce the problem on another branch?
  • Did the problem started happening recently i.e. in the new website (i.e. when theme is beautifulhugo) or was this a problem in the older version too (i.e. when theme is Syna)?
  • Can you reliably reproduce the issue? If not, please describe how often the problem occurs and under what conditions does it normally occur.
  • If the problem is related to working with files (e.g. opening or editing files), does the problem occur for all the files and folders? Does the problem occur only when working with local or remote files (e.g., on network drives), with specific type of file (e.g. .md or .html, etc.), with files with large size, with files with more number of lines, with files with a specific encoding? It there anything else specific about the files you are using?

Suggesting Enhancements

Before Submitting An Enhancement Suggestion

How Do I Submit A (Good) Enhancement Suggestion?

Pull Requests

Style guide (Git Commit Messages)

  • Use the present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference issues and pull requests liberally after the first line
  • When only changing documentation, include [ci skip] in the commit title
  • Consider starting the commit message with an applicable emoji:
    • 🎨 :art: when improving the format/structure of the code
    • 🐎 :racehorse: when improving performance
    • 🚱 :non-potable_water: when plugging memory leaks
    • 📝 :memo: when writing docs
    • 🐧 :penguin: when fixing something on Linux
    • 🍎 :apple: when fixing something on macOS
    • 🏁 :checkered_flag: when fixing something on Windows
    • 🐛 :bug: when fixing a bug
    • 🔥 :fire: when removing code or files
    • 💚 :green_heart: when fixing the CI build
    • ✅ :white_check_mark: when adding tests
    • 🔒 :lock: when dealing with security
    • ⬆️ :arrow_up: when upgrading dependencies
    • ⬇️ :arrow_down: when downgrading dependencies
    • 👕 :shirt: when removing linter warnings

Additional Notes

Issue Labels

Label Name Description
enhancement New feature or request
bug Something is not working as expected
question Further information is requested
feedback General feedback more than bug reports or feature requests
help wanted Extra attention is needed
good first issue Easy issues that would be good for new contributors
blocked Issues blocked/dependent on other issues
duplicate This issue or pull request already exists
wontfix This will not be worked on
invalid This doesn't seem right (e.g. user error)
wrong-repo Issues reported on the wrong repository

Pull Request Labels

Label Name Description
work-in-progress PRs which are still being worked on
testing To test new or existing features, functions, or code
needs-review To indicate that a pull request requires review
under-review To indicate that a pull request is under review

Installing a new theme

This website is built on Hugo framework. To install a new Hugo theme, please take the following steps:

Assumptions

  1. You have already installed Hugo on your machine
  2. You have git installed on your machine and you are familiar with basic git usage.

Adding a new theme

  • You can add a new theme as a submodule as follows:
git submodule init # If you haven't initialized before
git submodule add https://github.com/halogenica/beautifulhugo.git 
themes/beautifulhugo # This would add the beautifulhugo theme
  • The theme is successfully installed if you see it inside the /themes directory (for example, in this case you will see /themes/beautifulhugo/).
  • To use the theme, make sure that you set it accordingly in the config.toml:
theme = "theme_name"

Note: Here "theme_name" is the exact name of the theme as mentioned in the /themes directory (for example, in this case it will be theme = "beautifulhugo").

Adding a table

Here is a step-by-step demo about making a table:

Create a basic table

  • A vertical line | should be added to both the ends of each row.
  • Separate the columns by a vertical line |.
  • The column header can be separated from the remaining row by using three or more dashes ---.

For example, the below code will result in the table that follows it:

| Country| Capital City |
| --- | --- |
| Canada | Ottawa |
| Australia | Canberra |
| Egypt | Cairo |
Country Capital City
Canada Ottawa
Australia Canberra
Egypt Cairo

Here are the steps to format the table:

Text Alignment

  • To align text in the columns to the left, right, or center add a colon : to the left, right, or on both side of the dashes--- within the header row.
  • :--: left alignment
  • --:: right alignment
  • :-:: center alignment

For example, the below code will result in the table that follows it:

| Country| Capital City |
| :---: | :---: |
| Canada | Ottawa |
| Australia | Canberra |
| Egypt | Cairo |
Country Capital City
Canada Ottawa
Australia Canberra
Egypt Cairo

Going to next line

To go to next line in a row, use \.

| Country | Capital City |
| --- | --- |
| Canada | Ottawa |
| Australia | Canberra |
| Egypt | Cairo |
Country Capital City
Canada Ottawa
Australia Canberra
Egypt Cairo

Note: the text in the table can be further formatted. For example, adding links, inline code (words or phrases in backticks only, not code blocks).

Adding an image

Here is a step-by-step demo about how to add an image using an IDE:

  • Clone the website repository from https://github.com/researchsoft.
  • Upload the image to the folder website/static/images.
  • Add image details to appropriate .md file using the following code:
+++
title = ""
#weight =

[asset]
    image = "image_name_with_file_extension"
    url = "relevant_url"
    text = "image_short_description"
+++

Note:

  • Here "image_name_with_file_extension" is the exact name of the image as mentioned in the /static directory.
  • text is used to give a short description of the image. Please enter a short description of the image after the = sign.
  • url is an optional attribute. It is used if we want to hyperlink the image with some relevant link. Please enter the hyperlink after the = sign.
  • Image caption: ...

Step x: How to add caption?

Step (x+1): How to change size of the image?

Step (x+2): How to add alt text?

Adding Organizational Member Logos

What are Hugo Shortcodes?

Shortcodes are reusable snippets of code in Hugo (the static site generator that powers this website) that allow you to embed complex HTML structures into your Markdown content. Think of them as custom templates that can be called from content pages.

For example, instead of copying the same HTML code for displaying organizational member logos on multiple pages, we use a shortcode called org-members that can be invoked simply by writing:

{{< org-members >}}

This shortcode automatically renders all organizational member logos in a consistent grid layout. The shortcode files are stored in the layouts/shortcodes/ directory.

Adding a New Organizational Member Logo

When ReSA gains a new organizational member, follow these steps to add their logo to the website:

Step 1: Prepare the Logo Image

  • File format: SVG, PNG or JPG (SVG preferred overall, PNG preferred over JPG for logos with transparency)
  • Naming convention: Use a descriptive name (e.g., ASAP_FullColor.png, Sloan-logo.png)
  • Size: Logos should be reasonably sized (typically under 500KB). The website will automatically resize them to fit the grid.

Step 2: Upload the Logo

Upload the logo file to:

content/about/membership/images/

Via GitHub:

  1. Navigate to content/about/membership/images/
  2. Click Add file → Upload files
  3. Drag and drop your logo or click to select it
  4. Commit the file with a descriptive message (e.g., "Add ASAP organizational member logo")

Via Command Line:

# Copy your logo to the correct directory
cp /path/to/your-logo.png content/about/membership/images/

# Add and commit
git add content/about/membership/images/your-logo.png
git commit -m ":art: Add [Organization Name] member logo"
git push

Step 3: Update the Shortcode

Edit the file layouts/shortcodes/org-members.html to add the new organization to the grid.

The shortcode file contains a responsive grid layout with rows of 3 logos each. Find an appropriate location to add your new member (typically at the end, or in alphabetical order within their membership tier).

Add a new logo block:

<div class="col-md-4 logo-container">
<a href="https://organization-website.org/">
    <img src="/about/membership/images/your-logo.png" alt="Organization Name" class="logo-image">
</a>
</div>

For organizations without a logo (text-only display):

<div class="col-md-4 logo-container">
<a href="https://organization-website.org/" class="no-logo-text">Organization Name</a>
</div>

Important Notes:

  • Each row contains 3 logo containers (col-md-4)
  • When you add a 4th logo, start a new row: 
    <div class="row justify-content-center mt-5">
    <!-- new logos here -->
</div>
  • The mt-5 class adds vertical spacing between rows
  • The image path must be absolute from the site root: /about/membership/images/filename.png

Step 4: Test Your Changes

If testing locally:

hugo server

Then visit http://localhost:1313/about/membership/ to see how the logo appears in the grid.

Where the Organizational Members List Appears

The {{< org-members >}} shortcode is used in:

Updating the shortcode automatically updates the logo display on all these pages.