Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update readme and documentation #1124

Merged
merged 24 commits into from
Apr 14, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 1 addition & 71 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,73 +1,3 @@
# Contributing

## How do I contribute?

There are two logical ways to contribute to the code and content usrse.github.io, including (but not limited to):

- opening up an issue to ask a question, report a bug, or request a feature
- working on a change to the website and opening up a pull request to discuss

This guide will help you to communicate with usrse (if needed) and guide you with
proper steps to make your contribution.

## Communication

Whether you are opening a pull request or an issue, you might want to communicate with
others in the community first. How can you do this? You can:

- have discussion on the USRSE slack (usrse.slack.com) in the `#website` channel
- open an issue at https://www.github.com/usrse/usrse.github.io
- write an email to contact@us-rse.org (for more private questions)

It could be that you want to talk about a new feature or bug, and then follow up by opening
an issue at https://www.github.com/usrse/usrse.github.io/issues. It could also be
that you want to suggest and then work on a new feature, but you want to check first
that a pull request would be welcomed. Regardless of your need, the above channels
can offer you a means to do this.

### Teams

We have several teams on the repository that you can reference (@ "at") if you need help!

- @usrse-admin: should be used for more important discussion that should involve administrators.
- @usrse-maintainers: are referenced when a new pull request is open, and are primarily responsible for doing or assigning review.

## Making a Contribution

### Making Edits to the Website Repo
To make a contribution, you will need to edit the US RSE GitHub repo (https://github.com/USRSE/usrse.github.io).

Text, images, and other website assets go in different places. Here's a brief guide to a few key areas:
- The webpage text exist in markdown files (.md) in several places like `_events`, `_pages`, and `wg`. The best way to find the page you're trying to edit is to follow the path in the URL of the page itself. Example: editing the page for "https://us-rse.org/events/2022/2022-10-funder-talk-series/" would be in `_events` -> `2022` -> `2022-10-funder-talk-series.md`
- Small files like .png images go into `assets` -> `_img`
- Larger files like slides from a speaker series currently go into a read-only Google Drive. One exists for the speaker series [here](https://drive.google.com/drive/folders/1HiwQZgmXF30BSFDxEfQOfu68Hv4F4NwC?usp=share_link).
- You'll need to ask to add slides to that folder if you are not an editor.
- Managers will need to change the permissions of files added there to be read-only and provide a share link that is accessible to anyone with the link to view.


### Pull Requests

When making a pull request contribution, it is important to properly communicate the
gist of the contribution. If it is a simple code or editorial fix, simply
explaining this within the GitHub Pull Request (PR) will suffice. But if this
is a larger fix or enhancement, it should be first discussed with the project
leader or developers. See the [communication channels](#communication) for ways
to do this.

#### Pull Request Process

The repository comes with a [pull request template](PULL_REQUEST_TEMPLATE.md) that provides you with a checklist and
helpful reminders for these points.

1. All pull requests should be sent to the main branch, unless you are testing an integration, in which case you should cc @usrse-admin in an issue, or ask for help on the website channel of usrse.slack.com.
2. Follow the existing code style precedent.
3. Test and preview your PR locally, and tell the reviewers if you were not able to
4. If necessary, update the README.md.
5. The pull request must receive at least one review and approval by a repository maintainer (for small fixes) and two for larger changes or changes to content for merge, along with all tests passing.


#### Issue Process

We encourage all community members to open issues on the GitHub [issues board](https://www.github.com/usrse/usrse.github.io/issues) whether you have a question, feature request, or bug report. In the case that you do not
have a GitHub account, you are welcome to communicate your issue via [other avenues](#communication)
and a maintainer will create a GitHub issue on your behalf.
Please see the [README file](../README.md)
32 changes: 6 additions & 26 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,11 @@
<!--- Thank you for opening a pull request! Here are some helpful tips:

1. To solicit reviewers:
the @usrse-maintainers are automatically notified when you open this pull request
If you need additional reviewers you can:
(if you have permission to do so) assign the label "reviewers-needed"
if you are on the usrse slack, post a link to your PR there and ask for reviewers

2. To get help:
you can ask the question directly in this pull request for @usrse-maintainers
you can ask a question in the #website channel of usrse.slack.com
for important issues, you can @usrse-admin to alert all admins of the repository (use sparingly)
-->

<!--- Provide a general summary of your changes in the Title above -->

## Description
<!--- Describe your changes in detail. -->
<!--- Describe your changes. If it fixes an open issue, please link to the issue here. -->

## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->
<!--- If it fixes an open issue, please link to the issue here. -->

## Checklist:
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
- [ ] I have posted the link for the PR in the usrse slack (#website) to ask for reviewers
- [ ] I have previewed changes locally
- [ ] I have updated the README.md if necessary
<!---Check these off after you create the PR --->
- [ ] I have previewed changes locally or with CircleCI (runs when PR is created)
- [ ] I have posted the link for the PR in the US-RSE Slack (#website) to ask for reviewers


cc @usrse-maintainers
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm pretty sure usrse-maintainers will still be notified on PR creation without this line but I just want to confirm that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know that they will be notified, but regardless, that's not quite the right group. When sorting out the groups, I made usrse-maintainers non-SC members with merge permissions, and then there's a SC group as well. I think we want people putting the PR on Slack when they're ready for review? Especially because people need to preview and check tests first (so don't really want to alert folks until it's really ready). But maybe we do want some @ a group in the template?

<!---Ask questions if needed in the #website channel of US-RSE Slack --->
2 changes: 1 addition & 1 deletion .github/workflows/linting.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,4 @@ jobs:
exclude_patterns: supercomputing.org,https://pace.gatech.edu,https://www.linkedin.com,jobs.colorado.edu,zoom.us,danielskatz.org,usrse.github.io.wiki.git,ornl.gov,jobs.bnl.gov,https://www.rd-alliance.org/,https://uwhires.admin.washington.edu/,https://careers.umich.edu/,https://twitter.com/us_rse,https://twitter.com/us_rse/status/1447622175133945860,https://twitter.com/iancosden/status/1122937311644323841

# Exclude these files from the checker
exclude_files: README.md,SocialNetworks.yml,map.yml,_config.yml,tests/test_,.github/workflows,_posts/newsletters/
exclude_files: README.md,docs/events.md,docs/tests_ci.md,docs/local_previews.md,SocialNetworks.yml,map.yml,_config.yml,tests/test_,.github/workflows,_posts/newsletters/
Loading