-
Notifications
You must be signed in to change notification settings - Fork 82
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
Changes from all commits
Commits
Show all changes
24 commits
Select commit
Hold shift + click to select a range
cee380d
draft1
cmaimone d77d0d1
add links for related pages
cmaimone 2f72e72
exclude documentation file
cmaimone af69435
URL typo correction
cmaimone 2b2c5d3
more docs to the exclusion list
cmaimone 890e898
wording clarification
cmaimone e188a1b
wording clarification
cmaimone c6a740a
wording clarification
cmaimone e485c17
typo
cmaimone 0eb92d8
typo
cmaimone 9f26d18
wording clarification
cmaimone c2091c3
wording clarification
cmaimone 3a76b50
typo
cmaimone b418156
copyedit
cmaimone 0e0c025
clarifications
cmaimone 1ce7612
editing
cmaimone fa03b93
typo
cmaimone 5402de1
editing
cmaimone 5e73451
wording
cmaimone 3bfb28d
editing
cmaimone 29cf0e4
editing
cmaimone 36671ba
copyediting
cmaimone 2aa3bfe
typos, copyediting
cmaimone 4620636
copyediting
cmaimone File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
<!---Ask questions if needed in the #website channel of US-RSE Slack ---> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?