diff --git a/assets/images/help/discussions/github-discussions-example.png b/assets/images/help/discussions/github-discussions-example.png new file mode 100644 index 000000000000..c450a4bd99e1 Binary files /dev/null and b/assets/images/help/discussions/github-discussions-example.png differ diff --git a/assets/images/help/issues/issue-example.png b/assets/images/help/issues/issue-example.png new file mode 100644 index 000000000000..8da1777c6805 Binary files /dev/null and b/assets/images/help/issues/issue-example.png differ diff --git a/assets/images/help/projects/team-discussions-example.png b/assets/images/help/projects/team-discussions-example.png new file mode 100644 index 000000000000..974bf47161e5 Binary files /dev/null and b/assets/images/help/projects/team-discussions-example.png differ diff --git a/assets/images/help/pull_requests/pr-conversation-example.png b/assets/images/help/pull_requests/pr-conversation-example.png new file mode 100644 index 000000000000..3da37643e9ca Binary files /dev/null and b/assets/images/help/pull_requests/pr-conversation-example.png differ diff --git a/assets/images/help/pull_requests/pr-files-changed-example.png b/assets/images/help/pull_requests/pr-files-changed-example.png new file mode 100644 index 000000000000..c34bbec611f0 Binary files /dev/null and b/assets/images/help/pull_requests/pr-files-changed-example.png differ diff --git a/content/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion.md b/content/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion.md index b838d84d4e83..881a9fe8230f 100644 --- a/content/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion.md +++ b/content/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion.md @@ -12,7 +12,7 @@ versions: {% 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)." +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. 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 %}](/communities/maintaining-your-safety-on-github)." diff --git a/content/github/collaborating-with-issues-and-pull-requests/about-conversations-on-github.md b/content/github/collaborating-with-issues-and-pull-requests/about-conversations-on-github.md deleted file mode 100644 index 30e47dcb9f98..000000000000 --- a/content/github/collaborating-with-issues-and-pull-requests/about-conversations-on-github.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: About conversations on GitHub -intro: 'You can discuss specific projects and changes, as well as broader projects or team goals, using different types of discussions on {% data variables.product.product_name %}.' -redirect_from: - - /articles/about-discussions-in-issues-and-pull-requests/ - - /articles/about-conversations-on-github -versions: - free-pro-team: '*' - enterprise-server: '*' - github-ae: '*' -topics: - - Pull requests ---- - -### Discussions on {% data variables.product.product_name %} - -You can create and participate in issues, pull requests, and team discussions, depending on the type of conversation you'd like to have. - -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](/organizations/collaborating-with-your-team/about-team-discussions)." - -### Reacting to ideas in comments - -You can show your support or dissent for an idea in a conversation. When you add a reaction to a comment or the body of a team discussion, issue, or pull request, people subscribed to the conversation won't receive a notification. For more information about subscriptions, see {% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" or currentVersion ver_gt "enterprise-server@2.20" %}"[About notifications](/github/managing-subscriptions-and-notifications-on-github/about-notifications){% else %}"[Subscribing to and unsubscribing from notifications](/github/receiving-notifications-about-activity-on-github/subscribing-to-and-unsubscribing-from-notifications){% endif %}." - -![Example of an issue with reactions](/assets/images/help/repository/issue-reactions.png) - -{% if currentVersion == "free-pro-team@latest" %} - -{% tip %} - -**Tip:** You can also add reactions using your mobile device. - -{% endtip %} - -{% endif %} -### Following contribution guidelines - -Before you open an issue or pull request, check to see if the repository has contributing guidelines. The *CONTRIBUTING.md* file includes information about how the repository maintainer would like you to contribute ideas to the project. - -Similar to contributing guidelines, the repository maintainer may have included a template for information to include in an issue or pull request. Completing the prompts from the template may help you get a better response from maintainers. - -### Further reading - -- "[Setting up your project for healthy contributions](/communities/setting-up-your-project-for-healthy-contributions)" -- "[Using templates to encourage useful issues and pull requests](/communities/using-templates-to-encourage-useful-issues-and-pull-requests)" -- "[Moderating comments and conversations](/communities/moderating-comments-and-conversations)" -- "[Writing on {% data variables.product.prodname_dotcom %}](/articles/writing-on-github)" diff --git a/content/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request.md b/content/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request.md index 03a822616359..23be51fa29bf 100644 --- a/content/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request.md +++ b/content/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request.md @@ -36,7 +36,7 @@ To reply to an existing line comment, you'll need to navigate to the comment on **Tips:** - Pull request comments support the same [formatting](/categories/writing-on-github) as regular comments on {% data variables.product.product_name %}, such as @mentions, emoji, and references. -- You can [add reactions](/articles/about-conversations-on-github#reacting-to-ideas-in-comments) to comments in pull requests in the **Files changed** tab. +- You can add reactions to comments in pull requests in the **Files changed** tab. {% endtip %} diff --git a/content/github/collaborating-with-issues-and-pull-requests/overview.md b/content/github/collaborating-with-issues-and-pull-requests/getting-started.md similarity index 60% rename from content/github/collaborating-with-issues-and-pull-requests/overview.md rename to content/github/collaborating-with-issues-and-pull-requests/getting-started.md index 8226328af923..41bdc43748b1 100644 --- a/content/github/collaborating-with-issues-and-pull-requests/overview.md +++ b/content/github/collaborating-with-issues-and-pull-requests/getting-started.md @@ -1,12 +1,17 @@ --- -title: Overview +title: Getting started +shortTitle: Getting started intro: 'Learn about the {% data variables.product.prodname_dotcom %} flow and different ways to collaborate on and discuss your projects.' mapTopic: true +redirect_from: + - /github/collaborating-with-issues-and-pull-requests/overview versions: free-pro-team: '*' enterprise-server: '*' github-ae: '*' topics: - Pull requests + - Issues + - Discussions + - Fundamentals --- - diff --git a/content/github/collaborating-with-issues-and-pull-requests/index.md b/content/github/collaborating-with-issues-and-pull-requests/index.md index b822cfb4226a..24e82218236b 100644 --- a/content/github/collaborating-with-issues-and-pull-requests/index.md +++ b/content/github/collaborating-with-issues-and-pull-requests/index.md @@ -18,10 +18,10 @@ topics: ### Table of Contents -{% topic_link_in_list /overview %} +{% topic_link_in_list /getting-started %} + {% link_in_list /quickstart-for-communicating-on-github %} {% link_in_list /github-flow %} {% link_in_list /about-collaborative-development-models %} - {% link_in_list /about-conversations-on-github %} {% topic_link_in_list /working-with-forks %} {% link_in_list /about-forks %} {% link_in_list /configuring-a-remote-for-a-fork %} diff --git a/content/github/collaborating-with-issues-and-pull-requests/quickstart-for-communicating-on-github.md b/content/github/collaborating-with-issues-and-pull-requests/quickstart-for-communicating-on-github.md new file mode 100644 index 000000000000..ced825b3e71f --- /dev/null +++ b/content/github/collaborating-with-issues-and-pull-requests/quickstart-for-communicating-on-github.md @@ -0,0 +1,151 @@ +--- +title: Quickstart for communicating on GitHub +intro: 'You can discuss specific projects and changes, as well as broader ideas or team goals, using different types of discussions on {% data variables.product.product_name %}.' +miniTocMaxHeadingLevel: 4 +redirect_from: + - /articles/about-discussions-in-issues-and-pull-requests/ + - /github/collaborating-with-issues-and-pull-requests/about-conversations-on-github +versions: + free-pro-team: '*' + enterprise-server: '*' + github-ae: '*' +topics: + - Pull requests + - Issues + - Discussions + - Fundamentals +--- + +### Introduction + +{% data variables.product.product_name %} provides built-in collaborative communication tools allowing you to interact closely with your community. This quickstart guide will show you how to pick the right tool for your needs. + +{% if currentVersion == "free-pro-team@latest" %} +You can create and participate in issues, pull requests, {% data variables.product.prodname_discussions %}, and team discussions, depending on the type of conversation you'd like to have. +{% endif %} +{% if currentVersion ver_gt "enterprise-server@2.20" or currentVersion == "github-ae@latest" %} +You can create and participate in issues, pull requests and team discussions, depending on the type of conversation you'd like to have. +{% endif %} + +#### Issues +- are useful for discussing specific details of a project such as bug reports, planned improvements and feedback. +- are specific to a repository, and usually have a clear owner. +- are often referred to as {% data variables.product.prodname_dotcom %}'s bug-tracking system. + +#### Pull requests +- allow you to propose specific changes. +- allow you comment directly on proposed changes suggested by others. +- are specific to a repository. + +{% if currentVersion == "free-pro-team@latest" %} +#### {% data variables.product.prodname_discussions %} +- are like a forum, and are best used for open-form ideas and discussions where collaboration is important. +- may span many repositories. +- provide a collaborative experience outside the codebase, allowing the brainstorming of ideas, and the creation of a community knowledge base. +- often don’t have a clear owner. +- often do not result in an actionable task. +{% endif %} + +#### Team discussions +- can be started on your team's page for conversations that span across projects and don't belong in a specific issue or pull request. Instead of opening an issue in a repository to discuss an idea, you can include the entire team by having a conversation in a team discussion. +- allow you to hold discussions with your team about planning, analysis, design, user research and general project decision making in one place.{% if currentVersion ver_gt "enterprise-server@2.20" or currentVersion == "github-ae@latest" %} +- provide a collaborative experience outside the codebase, allowing the brainstorming of ideas. +- often don’t have a clear owner. +- often do not result in an actionable task.{% endif %} + +### Which discussion tool should I use? + +#### Scenarios for issues + +- I want to keep track of tasks, enhancements and bugs. +- I want to file a bug report. +- I want to share feedback about a specific feature. +- I want to ask a question about files in the repository. + +##### Issue example + +This example illustrates how a {% data variables.product.prodname_dotcom %} user created an issue in our documentation open source repository to make us aware of a bug, and discuss a fix. + +![Example of issue](/assets/images/help/issues/issue-example.png) + +- A user noticed that the blue color of the banner at the top of the page in the Chinese version of the {% data variables.product.prodname_dotcom %} Docs makes the text in the banner unreadable. +- The user created an issue in the repository, stating the problem and suggesting a fix (which is, use a different background color for the banner). +- A discussion ensues, and eventually, a consensus will be reached about the fix to apply. +- A contributor can then create a pull request with the fix. + +#### Scenarios for pull requests + +- I want to fix a typo in a repository. +- I want to make changes to a repository. +- I want to make changes to fix an issue. +- I want to comment on changes suggested by others. + +##### Pull request example + +This example illustrates how a {% data variables.product.prodname_dotcom %} user created a pull request in our documentation open source repository to fix a typo. + +In the **Conversation** tab of the pull request, the author explain why they created the pull request. +![Example of pull request - Conversation tab](/assets/images/help/pull_requests/pr-conversation-example.png) + +The **Files changed** tab of the pull request shows the implemented fix. +![Example of pull request - Files changed tab](/assets/images/help/pull_requests/pr-files-changed-example.png) + +- This contributor notices a typo in the repository. +- The user creates a pull request with the fix. +- A repository maintainer reviews the pull request, comments on it, and merges it. + +{% if currentVersion == "free-pro-team@latest" %} +#### Scenarios for {% data variables.product.prodname_discussions %} + +- I have a question that's not necessarily related to specific files in the repository. +- I want to share news with my collaborators, or my team. +- I want to start or participate in an open-ended conversation. +- I want to make an announcement to my community. + +##### {% data variables.product.prodname_discussions %} example + +This example shows the {% data variables.product.prodname_discussions %} welcome post for the {% data variables.product.prodname_dotcom %} Docs open source repository, and illustrates how the team wants to collaborate with their community. + +![Example of {% data variables.product.prodname_discussions %}](/assets/images/help/discussions/github-discussions-example.png) + +This community maintainer started a discussion to welcome the community, and to ask members to introduce themselves. This post fosters an inviting atmosphere for visitors and contributors. The post also clarifies that the team's happy to help with contributions to the repository. + +{% endif %} +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" or currentVersion == "github-ae@latest" %} +#### Scenarios for team discussions + +- I have a question that's not necessarily related to specific files in the repository. +- I want to share news with my collaborators, or my team. +- I want to start or participate in an open-ended conversation. +- I want to make an announcement to my team. + +{% if currentVersion == "free-pro-team@latest" %} +As you can see, team discussions are very similar to {% data variables.product.prodname_discussions %}. For {% data variables.product.prodname_dotcom_the_website %}, we recommend using {% data variables.product.prodname_discussions %} as the starting point for conversations. You can use {% data variables.product.prodname_discussions %} to collaborate with any community on {% data variables.product.prodname_dotcom %}. If you are part of an organization, and would like to initiate conversations within your organization or team within that organization, you should use team discussions. +{% endif %} + +##### Team discussion example + +This example shows a team post for the `octo-team` team. + +![Example of team discussion](/assets/images/help/projects/team-discussions-example.png) + +The `octocat` team member posted a team discussion, informing the team of various things: +- A team member called Mona started remote game events. +- There is a blog post describing how the teams uses {% data variables.product.prodname_actions %} to produce their docs. +- Material about the April All Hands is now available for all team members to view. + +{% endif %} + +### Next steps + +These examples showed you how to decide which is the best tool for your conversations on {% data variables.product.product_name %}. But this is only the beginning; there is so much more you can do to tailor these tools to your needs. + +For issues, for example, you can tag issues with labels for quicker searching and create issue templates to help contributors open meaningful issues. For more information, see "[About issues](/github/managing-your-work-on-github/about-issues#working-with-issues)" and "[About issue and pull request templates](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates)." + +For pull requests, you can create draft pull requests if your proposed changes are still a work in progress. Draft pull requests cannot be merged until they're marked as ready for review. For more information, see "[About pull requests](/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests)." + +{% if currentVersion == "free-pro-team@latest" %} +For {% data variables.product.prodname_discussions %}, you can set up a code of conduct and pin discussions that contain important information for your community. For more information, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)." +{% endif %} + +For team discussions, you can edit or delete discussions on a team's page, and you can configure notifications for team discussions. For more information, see "[About team discussions](/organizations/collaborating-with-your-team/about-team-discussions)." diff --git a/content/github/getting-started-with-github/be-social.md b/content/github/getting-started-with-github/be-social.md index 7dc41ac2541b..10a9d97010ad 100644 --- a/content/github/getting-started-with-github/be-social.md +++ b/content/github/getting-started-with-github/be-social.md @@ -38,6 +38,10 @@ Click **Watch** at the top of a repository to watch it. {% data reusables.support.ask-and-answer-forum %} +### Communicating on {% data variables.product.product_name %} + +{% data variables.product.product_name %} provides built-in collaborative communication tools, such as issues and pull requests, allowing you to interact closely with your community when building great software. For an overview of these tools, and information about the specificity of each, see "[Quickstart for communicating on {% data variables.product.prodname_dotcom %}](/github/collaborating-with-issues-and-pull-requests/quickstart-for-communicating-on-github)." + ### Doing even more #### Creating pull requests diff --git a/content/github/managing-your-work-on-github/sorting-issues-and-pull-requests.md b/content/github/managing-your-work-on-github/sorting-issues-and-pull-requests.md index 607b35394755..064fd27e2ec2 100644 --- a/content/github/managing-your-work-on-github/sorting-issues-and-pull-requests.md +++ b/content/github/managing-your-work-on-github/sorting-issues-and-pull-requests.md @@ -19,11 +19,11 @@ You can sort any filtered view by: * The least commented issues or pull requests * The newest updated issues or pull requests * The oldest updated issues or pull requests -* The most added [reaction](/articles/about-conversations-on-github#reacting-to-ideas-in-comments) on issues or pull requests +* The most added reaction on issues or pull requests {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-issue-pr %} -3. In the upper-right corner, select the Sort drop-down menu. +1. In the upper-right corner, select the Sort drop-down menu. ![Using the Sort drop-down tab](/assets/images/help/issues/issues_sort_dropdown.png) To clear your sort selection, click **Sort** > **Newest**. diff --git a/content/github/writing-on-github/autolinked-references-and-urls.md b/content/github/writing-on-github/autolinked-references-and-urls.md index 05c747ca8dad..3b7cc41e25d4 100644 --- a/content/github/writing-on-github/autolinked-references-and-urls.md +++ b/content/github/writing-on-github/autolinked-references-and-urls.md @@ -21,7 +21,7 @@ For more information on creating links, see "[Basic writing and formatting synta ### Issues and pull requests -Within conversations on {% data variables.product.product_name %}, references to issues and pull requests are automatically converted to shortened links. For more information, see "[About conversations on {% data variables.product.prodname_dotcom %}](/articles/about-conversations-on-github)." +Within conversations on {% data variables.product.product_name %}, references to issues and pull requests are automatically converted to shortened links. {% note %} diff --git a/content/organizations/collaborating-with-your-team/about-team-discussions.md b/content/organizations/collaborating-with-your-team/about-team-discussions.md index 513bb6920fb5..318dea42dcfc 100644 --- a/content/organizations/collaborating-with-your-team/about-team-discussions.md +++ b/content/organizations/collaborating-with-your-team/about-team-discussions.md @@ -43,7 +43,7 @@ For more information, see {% if currentVersion == "free-pro-team@latest" or curr ### Further reading -- "[About conversations on {% data variables.product.prodname_dotcom %}](/articles/about-conversations-on-github)" +- "[Quickstart for communicating on {% data variables.product.prodname_dotcom %}](/github/collaborating-with-issues-and-pull-requests/quickstart-for-communicating-on-github)" - "[About teams](/articles/about-teams)" - "[Creating a team discussion](/organizations/collaborating-with-your-team/creating-a-team-discussion)" - "[Editing or deleting a team discussion](/organizations/collaborating-with-your-team/editing-or-deleting-a-team-discussion)" diff --git a/data/allowed-topics.js b/data/allowed-topics.js index 6197601bee45..167e08b52c63 100644 --- a/data/allowed-topics.js +++ b/data/allowed-topics.js @@ -26,6 +26,7 @@ module.exports = [ 'Contacting sponsors', 'Containers', 'Codespaces', + 'Discussions', 'Docker', 'Events', 'Fundamentals', diff --git a/tests/fixtures/article-with-redirect-from-string.md b/tests/fixtures/article-with-redirect-from-string.md new file mode 100644 index 000000000000..b131c1284df8 --- /dev/null +++ b/tests/fixtures/article-with-redirect-from-string.md @@ -0,0 +1,5 @@ +--- +title: Article with redirect_from string +versions: '*' +redirect_from: /redirect-string +--- diff --git a/tests/routing/redirects.js b/tests/routing/redirects.js index e912e26559a4..0bb7eb158625 100644 --- a/tests/routing/redirects.js +++ b/tests/routing/redirects.js @@ -46,13 +46,12 @@ describe('redirects', () => { test('converts single `redirect_from` strings values into arrays', async () => { const page = await Page.init({ - relativePath: 'github/collaborating-with-issues-and-pull-requests/about-conversations-on-github.md', - basePath: path.join(__dirname, '../../content'), + relativePath: 'article-with-redirect-from-string.md', + basePath: path.join(__dirname, '../fixtures'), languageCode: 'en' }) page.buildRedirects() - const expected = '/en/github/collaborating-with-issues-and-pull-requests/about-conversations-on-github' - expect(page.redirects['/en/articles/about-discussions-in-issues-and-pull-requests']).toBe(expected) + expect(page.redirects['/redirect-string']).toBe('/en/article-with-redirect-from-string') }) describe('query params', () => {