Skip to content

Commit

Permalink
[Universe] Discussions Public Beta (github#16547)
Browse files Browse the repository at this point in the history
* Update README

* create structure for discussions landing page

* is everything broken

* [Universe] Dark mode (github#16545)

* Fix title

* Add Discussions product

* Correct title

* Correct title

* Move quickstart article

* Move quickstart back out into article

* Add and incorporate reusables

* Move information about search

* Draft conceptual information

* Draft best practices

* Draft further reading

* Draft product introduction

* Draft introduction

* Add author metadata

* Pluralize

* Fix typos

* Add introduction

* Bump Octicons

* Add some reusables

* Add images

* Revise article

* Draft article

* Change word

* 🔪 the gerund

* Add reusable

* Revise introduction

* Revise list

* Simplify

* Revise reusable

* Fix reusable; add context

* Rename reusable

* Deduplicate conceptual information

* 🔪 gerund

* Add link to further reading

* Move link and dispose of tip

* Delete space

* Add images

* Add conceptual section

* Add word

* Delete newline

* Revert package.json to state on main

* Tweak images

* Draft article

* Add product name

* Remove beta note

* Use product name for future-proofing

* Begin adding search information

* Fix copypasta

* little edits

* build out a bit more of the guides content

* Don't mention integrations for now

* Escape quote

* Remove authorship information for new defaults

* Finish drafting article

* Replace encoded character to match description

* Revise away inline link

* Accommodate 'for more information' in reusable

* Fix links

* Fix one last bit of copypasta

* Update indices

* Temporarily remove heading

* Update introduction

* Add new article 💀

* Remove commits from universe-2020-megabranch

* Add article 💀

* update with a very rough draft

* Add content about collaboration options to "About repositories"

* Add content about discussions to "About issues"

* Reorder content

* Add is:discussion query

* update with a few mmore fleshed out sections

* update with more structure

* Add reusable

* Add screenshots

* Clear way for actual procedural

* Discussions landing page "Communities" section (github#16692)

* Make button Overview-able

* Make card filtering more extensible

* Guard for missing attributes

* Use arbitrary dataset attributes

* Add section with discussions-community-card

* Tweak show more button behavior

* Conditionally show "Show more"

* Add beta_product frontmatter/label

* Remove beta callout note

* Hide changelog with no items

* Finish importing community info

* Fix borked markup

* Omit search abr

* Two columns should actually be two columns

* Use org image, change card layout

* Add two more examples

* Fix title

* Escape quote

* Escape another quote

* Draft article

* Lower case

* Relocate conceptual information

* Update qualifier name

* Draft article

* Add conceptual information and links

* Remove duplicative section

* Fix copypasta

* Revise reusable

* Update link

* Add content on categories

* Lint the discussions YAML file

* Update introduction and permissions

* ⚓

* Reusablize; fix link

* more planning content stuff

* Escape quotes

* Align prerequisites

* Soften

* Clean up prerequisites

* Fix titles; version; add screenshot

* Fix links

* Actually fix links

* Use better variable

* Mention pinning

* Update screenshots

* Add screenshot

* forgot to committ

* update with reusable

* add that screenshot

* beef up landing page a bit

* remove extra space

* messed that up

* fix hardcoded linkks weirdo

* fix tests

* update with permissions content

* update with placeholder

* filter out standalone category files from test

* update

* update @becca's ⚡ feedback

* update with more feedback

* so many updates

* fix links

* fix some more tests

* flesh some more things out

* update with further reading blah blah

* fix some things

* remove the gate-features label for beta ship only

* Add discussions video to product landing page (github#16759)

* Add discussions video placeholder

* This might work maybe

* fix tests

* apply all of @becca's and @lecoursen's ⚡ feedback ❤️

* rename to fix test

* Revert "Add discussions video to product landing page (github#16759)"

This reverts commit 2247e5d0881ca6b36cee421218e8341a7cc12ac7.

* update with test fix

Co-authored-by: Melanie Yarbrough <[email protected]>
Co-authored-by: Laura Coursen <[email protected]>
Co-authored-by: Matt Pollard <[email protected]>
Co-authored-by: Jason Etcovitch <[email protected]>
Co-authored-by: Sarah Schneider <[email protected]>
  • Loading branch information
6 people authored Dec 7, 2020
1 parent f312814 commit 754ceda
Show file tree
Hide file tree
Showing 101 changed files with 1,080 additions and 144 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ If you've found a problem, you can open an issue using a [template](https://gith

#### Solve an issue

If you have a solution to one of the open issues, you will need to fork the repository and submit a PR using the [template](https://github.com/github/docs/blob/main/CONTRIBUTING.md#pull-request-template) that is visible automatically in the pull request body. For more details about this process, please check out [Getting Started with Contributing](/CONTRIBUTING.md).
If you have a solution to one of the open issues, you will need to fork the repository and submit a pull request using the [template](https://github.com/github/docs/blob/main/CONTRIBUTING.md#pull-request-template) that is visible automatically in the pull request body. For more details about this process, please check out [Getting Started with Contributing](/CONTRIBUTING.md).

#### Join us in discussions

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/images/help/discussions/click-save.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/images/help/discussions/hero.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/images/help/discussions/most-helpful.png
Binary file added assets/images/help/discussions/search-result.png
Binary file added assets/images/help/settings/appearance-tab.png
8 changes: 4 additions & 4 deletions content/actions/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,18 +68,18 @@ versions:
<h2 class="mb-2 font-mktg h1">Code examples</h2>

<div class="pr-lg-3 mb-5 mt-3">
<input class="js-code-example-filter input-lg py-2 px-3 col-12 col-lg-8 form-control" placeholder="Search code examples" type="search" autocomplete="off" aria-label="Search code examples"/>
<input class="js-filter-card-filter input-lg py-2 px-3 col-12 col-lg-8 form-control" placeholder="Search code examples" type="search" autocomplete="off" aria-label="Search code examples"/>
</div>

<div class="d-flex flex-wrap gutter">
{% render 'code-example-card' for actionsCodeExamples as example %}
</div>

<button class="js-code-example-show-more btn btn-outline float-right">Show more {% octicon "arrow-right" %}</button>
<button class="js-filter-card-show-more btn btn-outline float-right">Show more {% octicon "arrow-right" %}</button>

<div class="js-code-example-no-results d-none py-4 text-center text-gray font-mktg">
<div class="js-filter-card-no-results d-none py-4 text-center text-gray font-mktg">
<div class="mb-3">{% octicon "search" width="24" %}</div>
<h3 class="text-normal">Sorry, there is no result for <strong class="js-code-example-filter-value"></strong></h3>
<h3 class="text-normal">Sorry, there is no result for <strong class="js-filter-card-value"></strong></h3>
<p class="my-3 f4">It looks like we don't have an example that fits your filter.<br>Try another filter or add your code example</p>
<a href="https://github.com/github/docs/blob/main/data/variables/action_code_examples.yml">Learn how to add a code example {% octicon "arrow-right" %}</a>
</div>
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
title: About discussions
intro: Use discussions to ask and answer questions, share information, make announcements, and conduct or participate in a conversation about a project on {% data variables.product.product_name %}.
versions:
free-pro-team: '*'
---

{% data reusables.discussions.beta %}

### About discussions

With {% data variables.product.prodname_discussions %}, the community for your project can create and participate in conversations within the project's repository. Discussions empower a project's maintainers, contributors, and visitors to gather and accomplish the following goals in a central location, without third-party tools.

- Share announcements and information, gather feedback, plan, and make decisions
- Ask questions, discuss and answer the questions, and mark the discussions as answered
- Foster an inviting atmosphere for visitors and contributors to discuss goals, development, administration, and workflows

![Discussions tab for a repository](/assets/images/help/discussions/hero.png)

You don't need to close a discussion like you close an issue or a pull request.

If a repository administrator or project maintainer enables discussions for a repository, anyone who visits the repository can create and participate in discussions for the repository. Repository administrators and project maintainers can manage discussions and discussion categories in a repository, and pin discussions to increase the visibility of the discussion. Moderators and collaborators can mark comments as answers, lock discussions, and convert issues to discussions. For more information, see "[Repository permission levels for an organization](/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization)."

For more information about management of discussions for your repository, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository)."

### About categories and formats for discussions

{% data reusables.discussions.you-can-categorize-discussions %} {% data reusables.discussions.about-categories-and-formats %} {% data reusables.discussions.repository-category-limit %}

For discussions with a question/answer format, an individual comment within the discussion can be marked as the discussion's answer. {% data reusables.discussions.github-recognizes-members %}

For more information, see "[Managing categories for discussions in your repository](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository)."

### Best practices for discussions

As a community member or maintainer, start a discussion to ask a question or discuss information that affects the community. For more information, see "[Collaborating with maintainers using discussions](/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions)."

Participate in a discussion to ask and answer questions, provide feedback, and engage with the project's community. For more information, see "[Participating in a discussion](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion)."

You can spotlight discussions that contain important, useful, or exemplary conversations among members in the community. For more information, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository#pinning-a-discussion)."

{% data reusables.discussions.you-can-convert-an-issue %} For more information, see "[Moderating discussions in your repository](/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion)."

### Sharing feedback

You can share your feedback about {% data variables.product.prodname_discussions %} with {% data variables.product.company_short %}. To join the conversation, see [`github/feedback`](https://github.com/github/feedback/discussions?discussions_q=category%3A%22Discussions+Feedback%22).

### Further reading

- "[About writing and formatting on {% data variables.product.prodname_dotcom %}](/github/writing-on-github/about-writing-and-formatting-on-github)"
- "[Searching discussions](/github/searching-for-information-on-github/searching-discussions)"
- "[About notifications](/github/managing-subscriptions-and-notifications-on-github/about-notifications)"
- "[Moderating comments and conversations](/github/building-a-strong-community/moderating-comments-and-conversations)"
- "[Maintaining your safety on {% data variables.product.prodname_dotcom %}](/github/building-a-strong-community/maintaining-your-safety-on-github)"
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
title: Collaborating with maintainers using discussions
shortTitle: Collaborating with maintainers
intro: You can contribute to the goals, plans, health, and community for a project on {% data variables.product.product_name %} by communicating with the maintainers of the project in a discussion.
permissions: People with read permissions to a repository can start and participate in discussions in the repository.
versions:
free-pro-team: '*'
---

{% data reusables.discussions.beta %}

### About collaboration with maintainers using discussions

{% data reusables.discussions.about-discussions %} If you use or contribute to a project, you can start a discussion to make suggestions and engage with maintainers and community members about your plans, questions, ideas, and feedback. For more information, see "[‎About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)."

{% data reusables.discussions.about-categories-and-formats %} Repository administrators and project maintainers can delete a discussion. For more information, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository#deleting-a-discussion)."

{% data reusables.discussions.github-recognizes-members %} These members appear in a list of the most helpful contributors to the project's discussions. As your project grows, you can grant higher access permissions to active members of your community. For more information, see "[Granting higher permissions to top contributors](/discussions/guides/granting-higher-permissions-to-top-contributors)"

![Most helpful contributors to discussions for a project](/assets/images/help/discussions/most-helpful.png)

For more information about participation in discussions, see "[Participating in a discussion](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion)."

### Prerequisites

To collaborate with maintainers using discussions, a repository administrator or project maintainer must enable discussions for the repository. For more information, see "[Enabling or disabling discussions for a repository](/github/administering-a-repository/enabling-or-disabling-github-discussions-for-a-repository)."

### Starting a discussion

{% data reusables.discussions.starting-a-discussion %}

### Filtering the list of discussions

You can search for discussions and filter the list of discussions in a repository. For more information, see "[Searching discussions](/github/searching-for-information-on-github/searching-discussions)."

{% data reusables.repositories.navigate-to-repo %}
{% data reusables.discussions.discussions-tab %}
1. In the **Search all discussions** field, type a search query. Optionally, to the right of the search field, click a button to further filter the results.
![Search bar and buttons for filtering discussions](/assets/images/help/discussions/search-and-filter-controls.png)
1. In the list of discussions, click the discussion you want to view.
![Discussion search results](/assets/images/help/discussions/search-result.png)

### Converting an issue to a discussion

{% data reusables.discussions.you-can-convert-an-issue %} For more information, see "[Moderating discussions in your repository](/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion#converting-an-issue-to-a-discussion)."

### Further reading

- "[About writing and formatting on {% data variables.product.prodname_dotcom %}](/github/writing-on-github/about-writing-and-formatting-on-github)"
- "[Maintaining your safety on {% data variables.product.prodname_dotcom %}](/github/building-a-strong-community/maintaining-your-safety-on-github)"
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
title: Collaborating with your community using discussions
shortTitle: Collaborating using discussions
intro: Gather and discuss your project with community members and other maintainers.
versions:
free-pro-team: '*'
---

{% data reusables.discussions.beta %}

{% link_in_list /about-discussions %}
{% link_in_list /participating-in-a-discussion %}
{% link_in_list /collaborating-with-maintainers-using-discussions %}

Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
title: Participating in a discussion
intro: You can converse with the community and maintainers in a forum within the repository for a project on {% data variables.product.product_name %}.
permissions: People with read permissions to a repository can participate in discussions in the repository.
versions:
free-pro-team: '*'
---

{% data reusables.discussions.beta %}

### About participation in a discussion

{% data reusables.discussions.about-discussions %} For more information, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)."

In addition to starting or viewing a discussion, you can comment in response to the original comment from the author of the discussion. You can also create a comment thread by replying to an individual comment that another community member made within the discussion, and react to comments with emoji. For more information about reactions, see "[About conversations on {% data variables.product.prodname_dotcom %}](/github/collaborating-with-issues-and-pull-requests/about-conversations-on-github#reacting-to-ideas-in-comments)."

You can block users and report disruptive content to maintain a safe and pleasant environment for yourself on {% data variables.product.product_name %}. For more information, see "[Maintaining your safety on {% data variables.product.prodname_dotcom %}](/github/building-a-strong-community/maintaining-your-safety-on-github)."

### Prerequisites

Discussions must be enabled for the repository for you to participate in a discussion in the repository. For more information, see "[Enabling or disabling discussions for a repository](/github/administering-a-repository/enabling-or-disabling-github-discussions-for-a-repository)."

### Creating a discussion

{% data reusables.discussions.starting-a-discussion %}

### Marking a comment as an answer

Discussion authors and users with the triage role or greater for a repository can mark a comment as the answer to a discussion in the repository.

{% data reusables.discussions.marking-a-comment-as-an-answer %}
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: Best practices for community conversations on GitHub
shortTitle: Best practices for community conversations
intro: 'You can use discussions to brainstorm with your team, and eventually move the conversation to a discussion when you are ready to scope out the work.'
versions:
free-pro-team: '*'
---

{% data reusables.discussions.beta %}

### Community conversations in {% data variables.product.prodname_discussions %}

Since {% data variables.product.prodname_discussions %} is an open forum, there is an opportunity to bring non-code collaboration into a project's repository and gather diverse feedback and ideas more quickly. You can help drive a productive conversation by:

- Asking pointed questions and follow-up questions to garner specific feedback
- Capture a diverse experience and distill it down to main points
- Open an issue to take action based on the conversation, where applicable

For more information about opening an issue and cross-referencing a discussion, see "[Opening an issue from a comment](/github/managing-your-work-on-github/opening-an-issue-from-a-comment)."

### Learning about conversations on GitHub

You can create and participate in discussions, issues, and pull requests, depending on the type of conversation you'd like to have.

You can use {% data variables.product.prodname_discussions %} to discuss big picture ideas, brainstorm, and spike out a project's specific details before committing it to an issue, which can then be scoped. Discussions are useful for teams if:
- You are in the discovery phase of a project and are still learning which director your team wants to go in
- You want to collect feedback from a wider community about a project
- You want to keep bug fixes, feature requests, and general conversations separate

Issues are useful for discussing specific details of a project such as bug reports and planned improvements. For more information, see "[About issues](/articles/about-issues)." Pull requests allow you to comment directly on proposed changes. For more information, see "[About pull requests](/articles/about-pull-requests)" and "[Commenting on a pull request](/articles/commenting-on-a-pull-request)."

{% data reusables.organizations.team-discussions-purpose %} For more information, see "[About team discussions](/articles/about-team-discussions)."

### Following contributing guidelines

Before you open a discussion, check to see if the repository has contributing guidelines. The CONTRIBUTING file includes information about how the repository maintainer would like you to contribute ideas to the project.

For more information, see "[Setting up your project for healthy contributions](/github/building-a-strong-community/setting-up-your-project-for-healthy-contributions)."

### Next steps

To continue learning about {% data variables.product.prodname_discussions %} and quickly create a discussion for your community, see "[Quickstart for {% data variables.product.prodname_discussions %}](/discussions/quickstart)."

### Further reading

- "[Setting up your project for healthy contributions](/articles/setting-up-your-project-for-healthy-contributions)"
- "[Using templates to encourage useful issues and pull requests](/github/building-a-strong-community/using-templates-to-encourage-useful-issues-and-pull-requests)"
- "[Moderating comments and conversations](/articles/moderating-comments-and-conversations)"
- "[Writing on {% data variables.product.prodname_dotcom %}](/articles/writing-on-github)"
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
title: Finding discussions across multiple repositories
intro: 'You can easily access every discussion you''ve created or participated in across multiple repositories.'
versions:
free-pro-team: '*'
---

{% data reusables.discussions.beta %}

### Finding discussions

1. Navigate to {% data variables.product.prodname_dotcom_the_website %}.
1. In the top-right corner of {% data variables.product.prodname_dotcom_the_website %}, click your profile photo, then click **Your enterprises**.
!["Your discussions" in drop-down menu for profile photo on {% data variables.product.product_name %}](/assets/images/help/discussions/your-discussions.png)
1. Toggle between **Created** and **Commented** to see the discussions you've created or participated in.

### Further reading

- "[Searching discussions](/github/searching-for-information-on-github/searching-discussions)"
- "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)"
- "[Managing discussions for your community](/discussions/managing-discussions-for-your-community)"
Loading

0 comments on commit 754ceda

Please sign in to comment.