search

brown-ccv / ccv-website-hugo

CCV Hugo Website
https://ccv.brown.edu
5 stars 9 forks source link

readme

CCV Website

This is the repo for Brown CCV's static website built with Hugo.

Getting Started

To make contributions, first clone the repo and install the dependencies:

git clone https://github.com/brown-ccv/ccv-website.git
cd ccv-website

Set up .env file:

Create a .env file with the contents of .env.example in the root of your project.

Serving to localhost

First, install the dependencies:

npm install

To run it locally:

npm run serve

Go to localhost:1313/

To build the site into the public/ folder. This generates all the files needed to publish the site, but doesn't start the server.

npm run build

Suggesting changes and reporting bugs

Open an issue using one of the provided templates. Follow the instructions and complete all items in the issue template. Consider assigning it to yourself and starting a pull request following the contribution guidelines below.

Contribution Guidelines

If you wish to contribute with content updates, style changes, new features, or bug fixes, read the full contributing guidelines below and follow the contribution workflow.

Conventions

GitLab Flow

Check the GitLab Flow Docs

The main branches are:

Changes happen in topic branches. Topic branch names start with the type of the change <change_type>-* (see types below). If multiple changes are expected in the same branch, name the branch updates-* and add the labels corresponding to the change type in your PR. Topic branches are created off master.

Once changes are done, a PR is submitted to master with the corresponding labels, and a review is requested from up to 3 reviewers (depending on the type of change - content (sometimes) or technical (always)).

Types of changes:

Conventional Commits

When committing your changes, use npm run commit instead of git commit -m. Follow the instructions on the terminal to create your conventional commit message. Click here to learn more. This is required and the technical reviewer should make sure only changes with conventional commits are merged.

Deployment environments

Production

Staging

Issues and PRs

A Slack channel gh-ccv-website is linked to this repository. Join that channel if you want to receive notifications when issues, PRs, and deployments are created.

Opening an Issue

Issues are welcome and are the recommended way to request or suggest changes. Use one of the templates provided and add labels as needed.

The suggestion label

Issues labeled with suggestion will be brought up for discussion during triage meetings. If a suggestion is approved, the issue will get the label next-up or fast-track depending on urgency and will be assigned to a member of website-dev or website-content. Priorities will also be discussed in the triage meetings and will be communicated to the assignee on the issue. If the suggestion is declined, a new label declined will be added and the issue will be closed. Declined suggestions can be brought up for discussion in future meetings.n

Submitting a PR

Use the template provided and fill in all the information requested and assign the appropriate reviewers. Make sure to fill this out correctly and check the appropriate checkboxes. A checklist for the reviewers will be created based on this.

A version of the website will be deployed for review to Heroku and a link to the deployed website will be added to the PR comments section. To view the website, click on view deployment. In addition, when the review site is deployed, the gh-ccv-website will be notified.

For content changes:

For new feature changes:

For hotfix, data, and style changes:

When a PR is merged into master, the topic branch that originates the PR is automatically deleted.

Notes for reviewers

A checklist will be created in the comments section of the PR. Follow those instructions and use the checklist. And review the website deployed to Heroku.

The reviewer who merged the PR into master is responsible for starting a PR to production and assigning it to the website-admin team once the waiting period (if applicable) is complete. Wait times are automatically tracked with the 1 day wait and 2.5 day wait labels and changed to ready when 24 or 60 non-weekend hours have lapsed since the last commit. The wait times are as follows:

The member from the website-admin will announce on the slack channel gh-ccv-website the waiting period for the PR to give everyone interested a chance to look at the staging site.

Reviewers

There are two types of reviewers. Reviewers are part of teams on GitHub and can find a checklist in the team discussion board.

Creating New Content

Sections:

News

This is the blog section. It's now on Medium.

Projects to Showcase on Home Page

Project, labs, initiatives, groups, collaborations, or anything we want to showcase. Items under this section will show up on the home page's carousel.

---
title: "{{ replace .Name "-" " " | title }}"
date: {{.Date}}
draft: false
team: ""
text: ""
image: "/images/<image.png>"
href: ""
cfa: "Launch the App" # call for action button: Read More, Learn More, Launch the App, More on Github...
---
npm run new content/english/projects/project.md

Documentation

Documentation is hosted on Gitbook. Check the docs here

For documentation related issues, open issues directly on the doc repo.

Data folder

People

data/people.yaml

- name: Ashley S. Lee
  team: Advanced Research Computing
  title: Data Scientist
  github_username: alee35
  brown_directory_uuid: 380094e2-6f9d-47cf-91ce-e636876a58cf
  bio: "Ashley received training in Biology and Data Science at the University of Virginia
    and dabbled in a variety of careers including Bus Driver, Bagel Slinger, and Chief
    Fiduciary at Smoothie King. She enjoys food and beverage, bodies of water, jokes,
    caring for her beloved dog and plants, and resenting her cat."
  image: ashley.jpg
Opportunities

data/opportunities.yaml 

- title: Research Services Support Specialist
  team: CCV Operations
  subteam: User Services
  link: "https://brown.wd5.myworkdayjobs.com/en-US/staff-careers-brown/job/180-George-Street/Research-Services-Support-Specialist_REQ151702"

Content folder

The majority of the website's content can be found under content/english/ in Markdown format.

To create new files under services use the command:

npm run new content/english/services/consulting/new_file.md
Guidelines for writing Markdown content

There are special shortcodes that can be used in the Markdown content files that generate styled html components that follow the website design. Find detailed information on how to write your markdown content and include shortcodes specific for CCV's website here.

Deskpro Knowledge Base Articles

It's possible to add content hosted in the Deskpro Knowledge Base. The content will be fetched at build time from the Deskpro RSS feed (https://ithelp.brown.edu/kb/ccv-website-articles.rss). For more information, reach out to CCV User Services team. If you are a content creator and are using Deskpro's Knowledge Base to serve content to the CCV Website, add the category Technical Services > CCV Website Articles to your article. Only articles in that category will be fetched.

To add that content to a Markdown file, use the rss shortcode with the article name as the only argument:

Note that the article name can be found in the article URL, for example, to add this article: https://ithelp.brown.edu/kb/articles/github-for-brown, use:

{{< rss "github-for-brown" >}}
Our work: Software and Workshops
GITHUB_TOKEN=
GITHUB_USER=
ORGANIZATION=brown-ccv,compbiocore,dscov-tutorials
repo: ccv-con
site_name: "CCV-Con Slide Archive"
authors:
 - name: "Fernando Gelin"
   github_user: fernandogelin
 - name: "Mary McGrath"
   github_user: mcmcgrath13
 - name: "Paul Stey"
   github_user: paulstey
repo_url: https://github.com/brown-ccv/ccv-con
site_description: "This repo houses links to the publically available slides from presentations at the CCV-Con Conference at Brown University."
docs_url:         
type: workshop    # required. choose one of [software, tutorial, workshop, documentation]

CCV Bot - Calendar

CCV's Calendar We also have an Events@brown calendar. https://event.brown.edu/ccv

Events

To add events to the website, simply invite ccv-bot@brown.edu to your event. Make sure to set a location, have a displayable name, and a nice typo-free, short description. The Bot needs to accept the invitation before it can be displayed on the website. CCV's Google Calendar is connect to Events@Brown and will show events in both places