{% octicon "search" width="24" %}
- Sorry, there is no result for
+Sorry, there is no result for
It looks like we don't have an example that fits your filter.
Try another filter or add your code example
Learn about requirements, guidelines, and the app submission process. +1. Add webhook events to the app to track user billing requests. For more information about the {% data variables.product.prodname_marketplace %} API, webhook events, and billing requests, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." -1. [Integrating with the {% data variables.product.prodname_marketplace %} API](/marketplace/integrating-with-the-github-marketplace-api/)
Before you can list your app on {% data variables.product.prodname_marketplace %}, you'll need to integrate billing flows using the {% data variables.product.prodname_marketplace %} API and webhook events. +1. Create a draft {% data variables.product.prodname_marketplace %} listing. For more information, see "[Drafting a listing for your app](/developers/github-marketplace/drafting-a-listing-for-your-app)." -1. [Listing on {% data variables.product.prodname_marketplace %}](/marketplace/listing-on-github-marketplace/)
Create a draft {% data variables.product.prodname_marketplace %} listing, configure webhook settings, and set up pricing plans. +1. Add a pricing plan. For more information, see "[Setting pricing plans for your listing](/developers/github-marketplace/setting-pricing-plans-for-your-listing)." -1. [Selling your app](/marketplace/selling-your-app/)
Learn about pricing plans, billing cycles, and how to receive payment from {% data variables.product.prodname_dotcom %} for your app. +1. Check whether your app meets the requirements for listing on {% data variables.product.prodname_marketplace %} as a free or a paid app. For more information, see "[Requirements for listing an app](/developers/github-marketplace/requirements-for-listing-an-app)." -1. [{% data variables.product.prodname_marketplace %} Insights](/marketplace/github-marketplace-insights/)
See how your app is performing in {% data variables.product.prodname_marketplace %}. You can use metrics collected by {% data variables.product.prodname_dotcom %} to guide your marketing campaign and be successful in {% data variables.product.prodname_marketplace %}. +1. Read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)." -1. [{% data variables.product.prodname_marketplace %} transactions](/marketplace/github-marketplace-transactions/)
Download and view transaction data for your {% data variables.product.prodname_marketplace %} listing. +1. Submit your listing for publication in {% data variables.product.prodname_marketplace %}, requesting verification if you want to sell the app. For more information, see "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication)." -### Reviewing your app +An onboarding expert will contact you with any questions or further steps. For example, if you have added a paid plan, you will need to complete the verification process and complete financial onboarding. As soon as your listing is approved the app is published to {% data variables.product.prodname_marketplace %}. -We want to make sure that the apps offered on {% data variables.product.prodname_marketplace %} are safe, secure, and well tested. The {% data variables.product.prodname_marketplace %} onboarding specialists will review your app to ensure that it meets all requirements. Follow the guidelines in these articles before submitting your app: +### Seeing how your app is performing +You can access metrics and transactions for your listing. For more information, see: -* [Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/) -* [Security review process](/marketplace/getting-started/security-review-process/) +- "[Viewing metrics for your listing](/developers/github-marketplace/viewing-metrics-for-your-listing)" +- "[Viewing transactions for your listing](/developers/github-marketplace/viewing-transactions-for-your-listing)" diff --git a/content/developers/github-marketplace/about-verified-creators.md b/content/developers/github-marketplace/about-verified-creators.md new file mode 100644 index 000000000000..a3c0eeb880fc --- /dev/null +++ b/content/developers/github-marketplace/about-verified-creators.md @@ -0,0 +1,43 @@ +--- +title: About verified creators +intro: 'Each organization that wants to sell apps on {% data variables.product.prodname_marketplace %} must follow a verification process. Their identity is checked and their billing process reviewed.' +versions: + free-pro-team: '*' +--- + +### About verified creators + +A verified creator is an organization that {% data variables.product.company_short %} has checked. Anyone can share their apps with other users on {% data variables.product.prodname_marketplace %} but only organizations that are verified by {% data variables.product.company_short %} can sell apps. For more information about organizations, see "[About organizations](/github/setting-up-and-managing-organizations-and-teams/about-organizations)." + +The verification process aims to protect users. For example, it verifies the seller's identity, checks that their {% data variables.product.product_name %} organization is set up securely, and that they can be contacted for support. + +After passing the verification checks, any apps that the organization lists on {% data variables.product.prodname_marketplace %} are shown with a verified creator badge {% octicon "verified" aria-label="Verified creator badge" %}. The organization can now add paid plans to any of their apps. Each app with a paid plan also goes through a financial onboarding process to check that it's set up to handle billing correctly. + + + +In addition to the verified creator badge, you'll also see badges for unverified and verified apps. These apps were published using the old method for verifying individual apps. + + + +For information on finding apps to use, see "[Searching {% data variables.product.prodname_marketplace %}](/github/searching-for-information-on-github/searching-github-marketplace)." + +### About the verification process + +The first time you request verification for a listing of one of your apps, you will enter the verification process. An onboarding expert will guide you through the process. This includes checking: + +- Profile information - The basic profile information is populated accurately and appropriately. +- Security - The organization has enabled two-factor authentication. +- Verified domain - The organization has verified the domain of the site URL. +- Purchase webhook event - The event is handled correctly by the app. + +When your organization is verified, all your apps are shown with a verified creator badge. You are now able to offer paid plans for any of your apps. + +For more information about the requirements for listing an app on {% data variables.product.prodname_marketplace %}, see "[Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/)." + +{% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit)." + +{% note %} + +**Note:** This verification process for apps replaces the previous process where individual apps were verified. The current process is similar to the verification process for actions. If you have apps that were verified under the old process, these will not be affected by the changes. The {% data variables.product.prodname_marketplace %} team will contact you with details of how to migrate to organization-based verification. + +{% endnote %} diff --git a/content/developers/github-marketplace/billing-customers.md b/content/developers/github-marketplace/billing-customers.md index 940892862bf6..ed6701d67117 100644 --- a/content/developers/github-marketplace/billing-customers.md +++ b/content/developers/github-marketplace/billing-customers.md @@ -13,17 +13,17 @@ versions: ### Understanding the billing cycle -Customers can choose a monthly or yearly billing cycle when they purchase your app. All changes customers make to the billing cycle and plan selection will trigger a `marketplace_purchase` event. You can refer to the `marketplace_purchase` webhook payload to see which billing cycle a customer selects and when the next billing date begins (`effective_date`). For more information about webhook payloads, see "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)." +Customers can choose a monthly or yearly billing cycle when they purchase your app. All changes customers make to the billing cycle and plan selection will trigger a `marketplace_purchase` event. You can refer to the `marketplace_purchase` webhook payload to see which billing cycle a customer selects and when the next billing date begins (`effective_date`). For more information about webhook payloads, see "[Webhook events for the {% data variables.product.prodname_marketplace %} API](/developers/github-marketplace/webhook-events-for-the-github-marketplace-api)." ### Providing billing services in your app's UI -Customers must be able to perform the following actions from your app's website: -- Customers must be able to modify or cancel their {% data variables.product.prodname_marketplace %} plans for personal and organizational accounts separately. +Customers should be able to perform the following actions from your app's website: +- Customers should be able to modify or cancel their {% data variables.product.prodname_marketplace %} plans for personal and organizational accounts separately. {% data reusables.marketplace.marketplace-billing-ui-requirements %} ### Billing services for upgrades, downgrades, and cancellations -Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)." +Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." You can use the `marketplace_purchase` webhook's `effective_date` key to determine when a plan change will occur and periodically synchronize the [List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan). @@ -33,7 +33,7 @@ When a customer upgrades their pricing plan or changes their billing cycle from {% data reusables.marketplace.marketplace-failed-purchase-event %} -For information about building upgrade and downgrade workflows into your app, see "[Upgrading and downgrading plans](/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans/)." +For information about building upgrade and downgrade workflows into your app, see "[Handling plan changes](/developers/github-marketplace/handling-plan-changes)." #### Downgrades and cancellations @@ -45,4 +45,4 @@ When a customer cancels a plan, you must: {% data reusables.marketplace.cancellation-clarification %} - Enable them to upgrade the plan through GitHub if they would like to continue the plan at a later time. -For information about building cancellation workflows into your app, see "[Cancelling plans](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/)." +For information about building cancellation workflows into your app, see "[Handling plan cancellations](/developers/github-marketplace/handling-plan-cancellations)." diff --git a/content/developers/github-marketplace/customer-experience-best-practices-for-apps.md b/content/developers/github-marketplace/customer-experience-best-practices-for-apps.md new file mode 100644 index 000000000000..4107fa4427f4 --- /dev/null +++ b/content/developers/github-marketplace/customer-experience-best-practices-for-apps.md @@ -0,0 +1,20 @@ +--- +title: Customer experience best practices for apps +intro: 'Guidelines for creating an app that will be easy to use and understand.' +shortTitle: Customer experience best practice +versions: + free-pro-team: '*' +--- + +If you follow these best practices it will help you to provide a good customer experience. + +### Customer communication + +- Marketing materials for the app should accurately represent the app's behavior. +- Apps should include links to user-facing documentation that describe how to set up and use the app. +- Customers should be able to see what type of plan they have in the billing, profile, or account settings section of the app. +- Customers should be able to install and use your app on both a personal account and an organization account. They should be able to view and manage the app on those accounts separately. + +### Plan management + +{% data reusables.marketplace.marketplace-billing-ui-requirements %} diff --git a/content/developers/github-marketplace/drafting-a-listing-for-your-app.md b/content/developers/github-marketplace/drafting-a-listing-for-your-app.md index 2f3be55bcfc8..11247e591d85 100644 --- a/content/developers/github-marketplace/drafting-a-listing-for-your-app.md +++ b/content/developers/github-marketplace/drafting-a-listing-for-your-app.md @@ -59,8 +59,8 @@ Once you've created a {% data variables.product.prodname_marketplace %} draft li ### Submitting your app -Once you've completed your {% data variables.product.prodname_marketplace %} listing, you can submit your listing for review from the **Overview** page. You'll need to read and accept the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)," and then you can click **Submit for review**. After you submit your app for review, the {% data variables.product.prodname_marketplace %} onboarding team will contact you with additional information about the onboarding process. You can learn more about the onboarding and security review process in "[Getting started with {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/)." +Once you've completed your {% data variables.product.prodname_marketplace %} listing, you can submit your listing for review from the **Overview** page. You'll need to read and accept the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)," and then you can click **Submit for review**. After you submit your app for review, an onboarding expert will contact you with additional information about the onboarding process. You can learn more about the onboarding and security review process in "[Getting started with {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/)." ### Removing a {% data variables.product.prodname_marketplace %} listing -If you no longer want to list your app in {% data variables.product.prodname_marketplace %}, contact [marketplace@github.com](mailto:marketplace@github.com) to remove your listing. +If you no longer want to list your app in {% data variables.product.prodname_marketplace %}, contact {% data variables.contact.contact_support %} to remove your listing. diff --git a/content/developers/github-marketplace/handling-new-purchases-and-free-trials.md b/content/developers/github-marketplace/handling-new-purchases-and-free-trials.md index 962262a47795..0c67eec8565a 100644 --- a/content/developers/github-marketplace/handling-new-purchases-and-free-trials.md +++ b/content/developers/github-marketplace/handling-new-purchases-and-free-trials.md @@ -28,7 +28,7 @@ GitHub then sends the [`marketplace_purchase`](/webhooks/event-payloads/#marketp Read the `effective_date` and `marketplace_purchase` object from the `marketplace_purchase` webhook to determine which plan the customer purchased, when the billing cycle starts, and when the next billing cycle begins. -If your app offers a free trial, read the `marketplace_purchase[on_free_trial]` attribute from the webhook. If the value is `true`, your app will need to track the free trial start date (`effective_date`) and the date the free trial ends (`free_trial_ends_on`). Use the `free_trial_ends_on` date to display the remaining days left in a free trial in your app's UI. You can do this in either a banner or in your [billing UI](/marketplace/selling-your-app/billing-customers-in-github-marketplace/#providing-billing-services-in-your-apps-ui). To learn how to handle cancellations before a free trial ends, see "[Cancelling plans](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/)." See "[Upgrading and downgrading plans](/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans/)" to find out how to transition a free trial to a paid plan when a free trial expires. +If your app offers a free trial, read the `marketplace_purchase[on_free_trial]` attribute from the webhook. If the value is `true`, your app will need to track the free trial start date (`effective_date`) and the date the free trial ends (`free_trial_ends_on`). Use the `free_trial_ends_on` date to display the remaining days left in a free trial in your app's UI. You can do this in either a banner or in your [billing UI](/marketplace/selling-your-app/billing-customers-in-github-marketplace/#providing-billing-services-in-your-apps-ui). To learn how to handle cancellations before a free trial ends, see "[Handling plan cancellations](/developers/github-marketplace/handling-plan-cancellations)." See "[Handling plan changes](/developers/github-marketplace/handling-plan-changes)" to find out how to transition a free trial to a paid plan when a free trial expires. See "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)" for an example of the `marketplace_purchase` event payload. diff --git a/content/developers/github-marketplace/index.md b/content/developers/github-marketplace/index.md index 34b9741c6147..0881424066ba 100644 --- a/content/developers/github-marketplace/index.md +++ b/content/developers/github-marketplace/index.md @@ -11,8 +11,10 @@ versions: {% topic_link_in_list /creating-apps-for-github-marketplace %} {% link_in_list /about-github-marketplace %} + {% link_in_list /about-verified-creators %} {% link_in_list /requirements-for-listing-an-app %} - {% link_in_list /security-review-process-for-submitted-apps %} + {% link_in_list /security-best-practices-for-apps %} + {% link_in_list /customer-experience-best-practices-for-apps %} {% link_in_list /viewing-metrics-for-your-listing %} {% link_in_list /viewing-transactions-for-your-listing %} {% topic_link_in_list /using-the-github-marketplace-api-in-your-app %} @@ -27,7 +29,7 @@ versions: {% link_in_list /writing-a-listing-description-for-your-app %} {% link_in_list /setting-pricing-plans-for-your-listing %} {% link_in_list /configuring-a-webhook-to-notify-you-of-plan-changes %} - {% link_in_list /submitting-your-listing-for-review %} + {% link_in_list /submitting-your-listing-for-publication %} {% topic_link_in_list /selling-your-app-on-github-marketplace %} {% link_in_list /pricing-plans-for-github-marketplace-apps %} {% link_in_list /billing-customers %} diff --git a/content/developers/github-marketplace/pricing-plans-for-github-marketplace-apps.md b/content/developers/github-marketplace/pricing-plans-for-github-marketplace-apps.md index bb33fe004f0e..aa9d924b4990 100644 --- a/content/developers/github-marketplace/pricing-plans-for-github-marketplace-apps.md +++ b/content/developers/github-marketplace/pricing-plans-for-github-marketplace-apps.md @@ -10,35 +10,45 @@ versions: -{% data variables.product.prodname_marketplace %} pricing plans can be free, flat rate, or per-unit, and GitHub lists the price in US dollars. Customers purchase your app using a payment method attached to their {% data variables.product.product_name %} account, without having to leave GitHub.com. You don't have to write code to perform billing transactions, but you will have to handle [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows) for purchase events. +{% data variables.product.prodname_marketplace %} pricing plans can be free, flat rate, or per-unit. Prices are set, displayed, and processed in US dollars. Paid plans are restricted to verified listings. + +Customers purchase your app using a payment method attached to their {% data variables.product.product_name %} account, without having to leave {% data variables.product.prodname_dotcom_the_website %}. You don't have to write code to perform billing transactions, but you will have to handle events from the {% data variables.product.prodname_marketplace %} API. For more information, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." If the app you're listing on {% data variables.product.prodname_marketplace %} has multiple plan options, you can set up corresponding pricing plans. For example, if your app has two plan options, an open source plan and a pro plan, you can set up a free pricing plan for your open source plan and a flat pricing plan for your pro plan. Each {% data variables.product.prodname_marketplace %} listing must have an annual and a monthly price for every plan that's listed. For more information on how to create a pricing plan, see "[Setting a {% data variables.product.prodname_marketplace %} listing's pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/)." -{% note %} +{% data reusables.marketplace.free-plan-note %} -**Note:** If you're listing an app on {% data variables.product.prodname_marketplace %}, you can't list your app with a free pricing plan if you offer a paid service outside of {% data variables.product.prodname_marketplace %}. +### Types of pricing plans -{% endnote %} +#### Free pricing plans -### Types of pricing plans +{% data reusables.marketplace.free-apps-encouraged %} + +Free plans are completely free for users. If you set up a free pricing plan, you cannot charge users that choose the free pricing plan for the use of your app. You can create both free and paid plans for your listing. + +All apps need to handle events for new purchases and cancellations. Apps that only have free plans do not need to handle events for free trials, upgrades, and downgrades. For more information, see: "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." + +If you add a paid plan to an app that you've already listed in {% data variables.product.prodname_marketplace %} as a free service, you'll need to request verification for the app and go through financial onboarding. + +#### Paid pricing plans -**Free pricing plans** are completely free for users. If you set up a free pricing plan, you cannot charge users that choose the free pricing plan for the use of your app. You can create both free and paid plans for your listing. Unverified free apps do not need to implement any billing flows. Free apps that are verified by Github need to implement billing flows for new purchases and cancellations, but do not need to implement billing flows for free trials, upgrades, and downgrades. If you add a paid plan to an app that you've already listed in {% data variables.product.prodname_marketplace %} as a free service, you'll need to resubmit the app for review. +There are two types of paid pricing plan: -**Flat rate pricing plans** charge a set fee on a monthly and yearly basis. +- Flat rate pricing plans charge a set fee on a monthly and yearly basis. -**Per-unit pricing plans** charge a set fee on either a monthly or yearly basis for a unit that you specify. A "unit" can be anything you'd like (for example, a user, seat, or person). +- Per-unit pricing plans charge a set fee on either a monthly or yearly basis for a unit that you specify. A "unit" can be anything you'd like (for example, a user, seat, or person). -**Marketplace free trials** provide 14-day free trials of OAuth or GitHub Apps to customers. When you [set up a Marketplace pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/), you can select the option to provide a free trial for flat-rate or per-unit pricing plans. +You may also want to offer free trials. These provide free, 14-day trials of OAuth or GitHub Apps to customers. When you set up a Marketplace pricing plan, you can select the option to provide a free trial for flat-rate or per-unit pricing plans. ### Free trials -Customers can start a free trial for any available paid plan on a Marketplace listing, but will not be able to create more than one free trial for a Marketplace product. +Customers can start a free trial for any paid plan on a Marketplace listing that includes free trials. However, customers cannot create more than one free trial per marketplace product. Free trials have a fixed length of 14 days. Customers are notified 4 days before the end of their trial period (on day 11 of the free trial) that their plan will be upgraded. At the end of a free trial, customers will be auto-enrolled into the plan they are trialing if they do not cancel. -See "[New purchases and free trials](/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/)" for details on how to handle free trials in your app. +For more information, see: "[Handling new purchases and free trials](/developers/github-marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/)." {% note %} diff --git a/content/developers/github-marketplace/requirements-for-listing-an-app.md b/content/developers/github-marketplace/requirements-for-listing-an-app.md index ead5d811bbc8..e54424b74ada 100644 --- a/content/developers/github-marketplace/requirements-for-listing-an-app.md +++ b/content/developers/github-marketplace/requirements-for-listing-an-app.md @@ -1,6 +1,6 @@ --- title: Requirements for listing an app -intro: 'Apps on {% data variables.product.prodname_marketplace %} must meet the requirements outlined on this page before our {% data variables.product.prodname_marketplace %} onboarding specialists will approve the listing.' +intro: 'Apps on {% data variables.product.prodname_marketplace %} must meet the requirements outlined on this page before the listing can be published.' redirect_from: - /apps/adding-integrations/listing-apps-on-github-marketplace/requirements-for-listing-an-app-on-github-marketplace/ - /apps/marketplace/listing-apps-on-github-marketplace/requirements-for-listing-an-app-on-github-marketplace/ @@ -12,49 +12,62 @@ versions: free-pro-team: '*' --- + +The requirements for listing an app on {% data variables.product.prodname_marketplace %} vary according to whether you want to offer a free or a paid app. -Before you submit your app for review, you must read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)." You'll accept the terms within your [draft listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/) on {% data variables.product.product_name %}. Once you've submitted your app, one of the {% data variables.product.prodname_marketplace %} onboarding specialists will reach out to you with more information about the onboarding process, and review your app to ensure it meets these requirements: +### Requirements for all {% data variables.product.prodname_marketplace %} listings -### User experience +All listings on {% data variables.product.prodname_marketplace %} should be for tools that provide value to the {% data variables.product.product_name %} community. When you submit your listing for publication, you must read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)." -- {% data variables.product.prodname_github_app %}s should have a minimum of 100 installations. -- {% data variables.product.prodname_oauth_app %}s should have a minimum of 200 users. +#### User experience requirements for all apps + +All listings should meet the following requirements, regardless of whether they are for a free or paid app. + +- Listings must not actively persuade users away from {% data variables.product.product_name %}. +- Listings must include valid contact information for the publisher. +- Listings must have a relevant description of the application. +- Listings must specify a pricing plan. - Apps must provide value to customers and integrate with the platform in some way beyond authentication. - Apps must be publicly available in {% data variables.product.prodname_marketplace %} and cannot be in beta or available by invite only. -- Apps cannot actively persuade users away from {% data variables.product.product_name %}. -- Marketing materials for the app must accurately represent the app's behavior. -- Apps must include links to user-facing documentation that describe how to set up and use the app. -- When a customer purchases an app and GitHub redirects them to the app's installation URL, the app must begin the OAuth flow immediately. For details, see "[Handling new purchases and free trials](/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/#step-3-authorization)." +- Apps must have webhook events set up to notify the publisher of any plan changes or cancellations using the {% data variables.product.prodname_marketplace %} API. For more information, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." -- Customers must be able to install your app and select repositories on both a personal and organization account. They should be able to view and manage those accounts separately. +For more information on providing a good customer experience, see "[Customer experience best practices for apps](/developers/github-marketplace/customer-experience-best-practices-for-apps)." -### Brand and listing +#### Brand and listing requirements for all apps -- Apps that use GitHub logos must follow the "[{% data variables.product.product_name %} Logos and Usage](https://github.com/logos)" guidelines. +- Apps that use GitHub logos must follow the {% data variables.product.company_short %} guidelines. For more information, see "[{% data variables.product.company_short %} Logos and Usage](https://github.com/logos)." - Apps must have a logo, feature card, and screenshots images that meet the recommendations provided in "[Writing {% data variables.product.prodname_marketplace %} listing descriptions](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/)." - Listings must include descriptions that are well written and free of grammatical errors. For guidance in writing your listing, see "[Writing {% data variables.product.prodname_marketplace %} listing descriptions](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/)." -### Security +To protect your customers, we recommend that you also follow security best practices. For more information, see "[Security best practices for apps](/developers/github-marketplace/security-best-practices-for-apps)." + +### Considerations for free apps -Apps will go through a security review before being listed on {% data variables.product.prodname_marketplace %}. A successful review will meet the requirements and follow the security best practices listed in "[Security review process](/marketplace/getting-started/security-review-process/)." For information on the review process, contact [marketplace@github.com](mailto:marketplace@github.com). +{% data reusables.marketplace.free-apps-encouraged %} + +### Requirements for paid apps + +In addition to the requirements for all apps above, each app that you offer as a paid service on {% data variables.product.prodname_marketplace %} must also meet the following requirements: + +- {% data variables.product.prodname_github_app %}s should have a minimum of 100 installations. +- {% data variables.product.prodname_oauth_app %}s should have a minimum of 200 users. +- All paid apps must handle {% data variables.product.prodname_marketplace %} purchase events for new purchases, upgrades, downgrades, cancellations, and free trials. For more information, see "[Billing requirements for paid apps](#billing-requirements-for-paid-apps)" below. +- Publishing organizations must have a verified domain and must enable two-factor authentication. For more information, see "[Requiring two-factor authentication in your organization](/github/setting-up-and-managing-organizations-and-teams/requiring-two-factor-authentication-in-your-organization.") -### Billing flows +When you are ready to publish the app on {% data variables.product.prodname_marketplace %} you must request verification for the listing. -Your app must integrate [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows) using the [{% data variables.product.prodname_marketplace %} webhook event](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/). +{% note %} -#### Free apps +The verification process is open to organizations. {% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit)." -{% data reusables.marketplace.free-apps-encouraged %} If you are listing a free app, you'll need to meet these requirements: +{% endnote %} -- Customers must be able to see that they have a free plan in the billing, profile, or account settings section of the app. -- When a customer cancels your app, you must follow the flow for [cancelling plans](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/). +### Billing requirements for paid apps -#### Paid apps +Your app does not need to handle payments but does need to use {% data variables.product.prodname_marketplace %} purchase events to manage new purchases, upgrades, downgrades, cancellations, and free trials. For information about how integrate these events into your app, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." -To offer your app as a paid service, you'll need to meet these requirements to list your app on {% data variables.product.prodname_marketplace %}: +Using GitHub's billing API allows customers to purchase an app without leaving GitHub and to pay for the service with the payment method already attached to their {% data variables.product.product_name %} account. -- To sell your app in {% data variables.product.prodname_marketplace %}, it must use GitHub's billing system. Your app does not need to handle payments but does need to use "[{% data variables.product.prodname_marketplace %} purchase events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)" to manage new purchases, upgrades, downgrades, cancellations, and free trials. See "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)" to learn about how to integrate these events into your app. Using GitHub's billing system allows customers to purchase an app without leaving GitHub and pay for the service with the payment method already attached to their {% data variables.product.product_name %} account. - Apps must support both monthly and annual billing for paid subscriptions purchases. - Listings may offer any combination of free and paid plans. Free plans are optional but encouraged. For more information, see "[Setting a {% data variables.product.prodname_marketplace %} listing's pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/)." -{% data reusables.marketplace.marketplace-billing-ui-requirements %} diff --git a/content/developers/github-marketplace/security-best-practices-for-apps.md b/content/developers/github-marketplace/security-best-practices-for-apps.md new file mode 100644 index 000000000000..fac3d2fcf682 --- /dev/null +++ b/content/developers/github-marketplace/security-best-practices-for-apps.md @@ -0,0 +1,60 @@ +--- +title: Security best practices for apps +intro: 'Guidelines for preparing a secure app to share on {% data variables.product.prodname_marketplace %}.' +redirect_from: + - /apps/marketplace/getting-started/security-review-process/ + - /marketplace/getting-started/security-review-process + - /developers/github-marketplace/security-review-process-for-submitted-apps +shortTitle: Security best practice +versions: + free-pro-team: '*' +--- + +If you follow these best practices it will help you to provide a secure user experience. + +### Authorization, authentication, and access control + +We recommend creating a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[Differences between GitHub Apps and OAuth Apps](/apps/differences-between-apps/)" for more details. +- Apps should use the principle of least privilege and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality. For more information, see [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) in Wikipedia. +- Apps should provide customers with a way to delete their account, without having to email or call a support person. +- Apps should not share tokens between different implementations of the app. For example, a desktop app should have a separate token from a web-based app. Individual tokens allow each app to request the access needed for GitHub resources separately. +- Design your app with different user roles, depending on the functionality needed by each type of user. For example, a standard user should not have access to admin functionality, and billing managers might not need push access to repository code. +- Apps should not share service accounts such as email or database services to manage your SaaS service. +- All services used in your app should have unique login and password credentials. +- Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties. +- Apps should not use personal access tokens to authenticate and should authenticate as an [OAuth App](/apps/about-apps/#about-oauth-apps) or a [GitHub App](/apps/about-apps/#about-github-apps): + - OAuth Apps should authenticate using an [OAuth token](/apps/building-oauth-apps/authorizing-oauth-apps/). + - GitHub Apps should authenticate using either a [JSON Web Token (JWT)](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app), [OAuth token](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/), or [installation access token](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation). + +### Data protection + +- Apps should encrypt data transferred over the public internet using HTTPS, with a valid TLS certificate, or SSH for Git. +- Apps should store client ID and client secret keys securely. We recommend storing them as [environmental variables](http://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables). +- Apps should delete all GitHub user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with GitHub. +- Apps should not require the user to provide their GitHub password. +- Apps should encrypt tokens, client IDs, and client secrets. + +### Logging and monitoring + +Apps should have logging and monitoring capabilities. App logs should be retained for at least 30 days and archived for at least one year. +A security log should include: + +- Authentication and authorization events +- Service configuration changes +- Object reads and writes +- All user and group permission changes +- Elevation of role to admin +- Consistent timestamping for each event +- Source users, IP addresses, and/or hostnames for all logged actions + +### Incident response workflow + +To provide a secure experience for users, you should have a clear incident response plan in place before listing your app. We recommend having a security and operations incident response team in your company rather than using a third-party vendor. You should have the capability to notify {% data variables.product.product_name %} within 24 hours of a confirmed incident. + +For an example of an incident response workflow, see the "Data Breach Response Policy" on the [SANS Institute website](https://www.sans.org/information-security-policy/). A short document with clear steps to take in the event of an incident is more valuable than a lengthy policy template. + +### Vulnerability management and patching workflow + +You should conduct regular vulnerability scans of production infrastructure. You should triage the results of vulnerability scans and define a period of time in which you agree to remediate the vulnerability. + +If you are not ready to set up a full vulnerability management program, it's useful to start by creating a patching process. For guidance in creating a patch management policy, see this TechRepublic article "[Establish a patch management policy](https://www.techrepublic.com/blog/it-security/establish-a-patch-management-policy-87756/)." diff --git a/content/developers/github-marketplace/security-review-process-for-submitted-apps.md b/content/developers/github-marketplace/security-review-process-for-submitted-apps.md deleted file mode 100644 index d1dc369feebf..000000000000 --- a/content/developers/github-marketplace/security-review-process-for-submitted-apps.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Security review process for submitted apps -intro: 'GitHub''s security team reviews all apps submitted to {% data variables.product.prodname_marketplace %} to ensure that they meet security requirements. Follow these best practices to be prepared for the review process.' -redirect_from: - - /apps/marketplace/getting-started/security-review-process/ - - /marketplace/getting-started/security-review-process -versions: - free-pro-team: '*' ---- - - - -After you've submitted your app for approval, the GitHub security team will request that you complete a security questionnaire about your app and overall security program. As part of the review, you will have the option to provide documentation to support your responses. You must submit two required documents before your app will be approved for {% data variables.product.prodname_marketplace %}: an [incident response plan](#incident-response-plan) and [vulnerability management workflow](#vulnerability-management-workflow). - - -### Security best practices - -Follow these best practices to have a successful security review and provide a secure user experience. - -#### Authorization, authentication, and access control - -We recommend submitting a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[Differences between GitHub Apps and OAuth Apps](/apps/differences-between-apps/)" for more details. -- Apps must use the "[principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)" and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality. -- Apps must provide customers with a way to delete their account, without having to email or call a support person. -- Apps should not share tokens between different implementations of the app. For example, a desktop app should have a separate token from a web-based app. Individual tokens allow each app to request the access needed for GitHub resources separately. -- Design your app with different user roles, depending on the functionality needed by each type of user. For example, a standard user should not have access to admin functionality, and billing managers might not need push access to repository code. -- Your app should not share service accounts such as email or database services to manage your SaaS service. -- All services used in your app should have unique login and password credentials. -- Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties. -- Apps cannot use personal access tokens to authenticate and must authenticate as an [OAuth App](/apps/about-apps/#about-oauth-apps) or [GitHub App](/apps/about-apps/#about-github-apps): - - OAuth Apps must authenticate using an [OAuth token](/apps/building-oauth-apps/authorizing-oauth-apps/). - - GitHub Apps must authenticate using either a [JSON Web Token (JWT)](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app), [OAuth token](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/), or [installation access token](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation). - -#### Data protection - -- Apps must encrypt data transferred over the public internet using HTTPS, with a valid TLS certificate, or SSH for Git. -- Apps must store client ID and client secret keys securely. We recommend storing them as [environmental variables](http://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables). -- Apps must delete all GitHub user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with GitHub. -- Apps cannot require the user to provide their GitHub password. -- Apps should encrypt tokens, client IDs, and client secrets. - -#### Logging and monitoring - -- Apps must have logging and monitoring capabilities. App logs must be retained for at least 30 days and archived for at least one year. -A security log should include: - - Authentication and authorization events - - Service configuration changes - - Object reads and writes - - All user and group permission changes - - Elevation of role to admin - - Consistent timestamping for each event - - Source users, IP addresses, and/or hostnames for all logged actions - -#### Incident response workflow - -- To partner with GitHub, you are required to have an [incident response plan](#incident-response-plan) in place before submitting your {% data variables.product.prodname_marketplace %} app listing. -- We recommend having a security and operations incident response team in your company rather than using a third-party vendor. -- You should have the capability to notify GitHub within 24 hours of a confirmed incident. -- You should familiarize yourself with sections 3.7.5 - 3.7.5.6 of the [{% data variables.product.prodname_marketplace %} Developer Agreement](/github/site-policy/github-marketplace-developer-agreement#3-restrictions-and-responsibilities), which include additional details on incident response workflow requirements. - -#### Vulnerability management and patching workflow - -- You should conduct regular vulnerability scans of production infrastructure. -- You should triage the results of vulnerability scans and define a period of time in which you agree to remediate the vulnerability. -- You should familiarize yourself with section 3.7.3 of the [{% data variables.product.prodname_marketplace %} Developer Agreement](/github/site-policy/github-marketplace-developer-agreement#3-restrictions-and-responsibilities), which includes additional details on vulnerability management and patching workflows requirements. - -### Security program documentation - -During the Marketplace security review, you will be asked to submit your incident response plan and vulnerability management workflow. Each document must include a company-branded statement signed by management with a date stamp. - -#### Incident response plan -Your incident response plan documentation must include the current process that your company follows, who is accountable, and the person to contact or expect contact from if an incident occurs. The "[NIST Computer Security Incident Handling Guide](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-61r2.pdf)" is a great example of a document that covers incident response in general. Section 2.3 "Incident Response Policy, Plan, and Procedure Creation" specifically covers the policy. Another great example is the "[SANS Data Breach Response Policy](https://www.sans.org/security-resources/policies/general/pdf/data-breach-response)." - -#### Vulnerability management workflow -Your vulnerability management workflow documentation must include the current process that your company follows for vulnerability management and the patching process used. If you don't have a full vulnerability management program, it might help to start by creating a patching process. For guidance in creating a patch management policy, read the article "[Establish a patch management policy](https://www.techrepublic.com/blog/it-security/establish-a-patch-management-policy-87756/)." - -{% note %} - -**Note:** The incident response and vulnerability management workflow documents aren't expected to be massive formal policy or program documents. A page or two about what you do is more valuable than a lengthy policy template. - -{% endnote %} - -#### GitHub Marketplace security program questionnaire - -During the app submission process, our {% data variables.product.prodname_marketplace %} onboarding team will also send you a questionnaire requesting information about your security practices. This document will serve as a written record attesting: - -- The authentication method and scopes required by your app. -- That you're not requesting more scopes or {% data variables.product.product_name %} access than is needed for the app to perform its intended functionality, taking OAuth limitations and use of {% data variables.product.prodname_github_app %}s into account. -- The use of any third-party services or infrastructure, such as SaaS, PaaS, or IaaS. -- An incident response procedure exists. -- Your app's method of key/token handling. -- That a responsible disclosure policy and process in place or plans to implement one within six months. -- Your vulnerability management workflow or program. -- That you have logging and monitoring capabilities. You must also provide evidence that any relevant app logs are retained for at least 30 days and archived for at least one year. diff --git a/content/developers/github-marketplace/setting-pricing-plans-for-your-listing.md b/content/developers/github-marketplace/setting-pricing-plans-for-your-listing.md index 205978a5f65e..9ab919817d89 100644 --- a/content/developers/github-marketplace/setting-pricing-plans-for-your-listing.md +++ b/content/developers/github-marketplace/setting-pricing-plans-for-your-listing.md @@ -1,6 +1,6 @@ --- title: Setting pricing plans for your listing -intro: 'When [listing your app on {% data variables.product.prodname_marketplace %}](/marketplace/listing-on-github-marketplace/), you can choose to provide your app as a free service or sell your app. If you plan to sell your app, you can create different pricing plans for different feature tiers.' +intro: 'When you list your app on {% data variables.product.prodname_marketplace %}, you can choose to provide your app as a free service or sell your app. If you plan to sell your app, you can create different pricing plans for different feature tiers.' redirect_from: - /apps/adding-integrations/managing-pricing-and-payments-for-a-github-marketplace-listing/setting-a-github-marketplace-listing-s-pricing-plan/ - /apps/marketplace/managing-pricing-and-payments-for-a-github-marketplace-listing/setting-a-github-marketplace-listing-s-pricing-plan/ @@ -17,57 +17,52 @@ versions: free-pro-team: '*' --- +### About setting pricing plans +If you want to sell an app on {% data variables.product.prodname_marketplace %}, you need to request verification when you publish the listing for your app. During the verification process, an onboarding expert checks the organization's identity and security settings. The onboarding expert will also take the organization through financial onboarding. For more information, see: "[Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/)." -### Creating pricing plans - -To learn about the types of pricing plans that {% data variables.product.prodname_marketplace %} offers, see "[{% data variables.product.prodname_marketplace %} Pricing Plans](/marketplace/selling-your-app/github-marketplace-pricing-plans/)." You'll also find helpful billing guidelines in "[Selling your app](/marketplace/selling-your-app/)." - -Pricing plans can be in the draft or published state. If you haven't submitted your {% data variables.product.prodname_marketplace %} listing for approval, a published listing will function the same way as draft listings until your app is approved and listed on {% data variables.product.prodname_marketplace %}. Draft listings allow you to create and save new pricing plans without making them available on your {% data variables.product.prodname_marketplace %} listing page. Once you publish the pricing plan, it's available for customers to purchase immediately. You can publish up to 10 pricing plans. +{% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit)." -To create a pricing plan for your {% data variables.product.prodname_marketplace %} listing, click **Plans and pricing** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). If you haven't created a {% data variables.product.prodname_marketplace %} listing yet, read "[Creating a draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/)" to learn how. - -When you click **New draft plan**, you'll see a form that allows you to customize your pricing plan. You'll need to configure the following fields to create a pricing plan: +{% data variables.product.prodname_marketplace %} offers several different types of pricing plan. For detailed information, see "[Pricing plans for {% data variables.product.prodname_marketplace %}](/developers/github-marketplace/pricing-plans-for-github-marketplace-apps)." -#### Plan name +### About saving pricing plans -Your pricing plan's name will appear on your {% data variables.product.prodname_marketplace %} app's landing page. You can customize the name of your pricing plan to align to the plan's resources, the size of the company that will use the plan, or anything you'd like. +You can save pricing plans in a draft or published state. If you haven't submitted your {% data variables.product.prodname_marketplace %} listing for approval, a published plan will function in the same way as a draft plan until your listing is approved and shown on {% data variables.product.prodname_marketplace %}. Draft plans allow you to create and save new pricing plans without making them available on your {% data variables.product.prodname_marketplace %} listing page. Once you publish a pricing plan on a published listing, it's available for customers to purchase immediately. You can publish up to 10 pricing plans. -#### Pricing models +For guidelines on billing customers, see "[Billing customers](/developers/github-marketplace/billing-customers)." -##### Free plans - -{% data reusables.marketplace.free-apps-encouraged %} A free plan still requires you to handle [new purchase](/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/) and [cancellation](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/) billing flows. See "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)" for more details. - -##### Flat-rate plans +### Creating pricing plans -Flat-rate pricing plans allow you to offer your service to customers for a flat-rate fee. {% data reusables.marketplace.marketplace-pricing-free-trials %} +To create a pricing plan for your {% data variables.product.prodname_marketplace %} listing, click **Plans and pricing** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). For more information, see "[Creating a draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/)." -You must set a price for both monthly and yearly subscriptions in U.S. Dollars for flat-rate plans. +When you click **New draft plan**, you'll see a form that allows you to customize your pricing plan. You'll need to configure the following fields to create a pricing plan: -##### Per-unit plans +- **Plan name** - Your pricing plan's name will appear on your {% data variables.product.prodname_marketplace %} app's landing page. You can customize the name of your pricing plan to align with the plan's resources, the size of the company that will use the plan, or anything you'd like. -Per-unit pricing allows you to offer your app in units. For example, a unit can be a person, seat, or user. You'll need to provide a name for the unit and set a price for both monthly and yearly subscriptions, in U.S. Dollars. +- **Pricing models** - There are three types of pricing plan: free, flat-rate, and per-unit. All plans require you to process new purchase and cancellation events from the marketplace API. In addition, for paid plans: -#### Available for + - You must set a price for both monthly and yearly subscriptions in US dollars. + - Your app must process plan change events. + - You must request verification to publish a listing with a paid plan. + - {% data reusables.marketplace.marketplace-pricing-free-trials %} -{% data variables.product.prodname_marketplace %} pricing plans can apply to **Personal and organization accounts**, **Personal accounts only**, or **Organization accounts only**. For example, if your pricing plan is per-unit and provides multiple seats, you would select **Organization accounts only** because there is no way to assign seats to people in an organization from a personal account. + For detailed information, see "[Pricing plans for {% data variables.product.prodname_marketplace %} apps](/developers/github-marketplace/pricing-plans-for-github-marketplace-apps)" and "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." -#### Short description +- **Available for** - {% data variables.product.prodname_marketplace %} pricing plans can apply to **Personal and organization accounts**, **Personal accounts only**, or **Organization accounts only**. For example, if your pricing plan is per-unit and provides multiple seats, you would select **Organization accounts only** because there is no way to assign seats to people in an organization from a personal account. -Write a brief summary of the details of the pricing plan. The description might include the type of customer the plan is intended for or the resources the plan includes. +- **Short description** - Write a brief summary of the details of the pricing plan. The description might include the type of customer the plan is intended for or the resources the plan includes. -#### Bullets +- **Bullets** - You can write up to four bullets that include more details about your pricing plan. The bullets might include the use cases of your app or list more detailed information about the resources or features included in the plan. -You can write up to four bullets that include more details about your pricing plan. The bullets might include the use cases of your app or list more detailed information about the resources or features included in the plan. +{% data reusables.marketplace.free-plan-note %} ### Changing a {% data variables.product.prodname_marketplace %} listing's pricing plan -If a pricing plan for your {% data variables.product.prodname_marketplace %} plan is no longer needed or if you need to adjust pricing details, you can remove it. +If a pricing plan for your {% data variables.product.prodname_marketplace %} listing is no longer needed, or if you need to adjust pricing details, you can remove it.  -Once you publish a pricing plan for an app already listed in the {% data variables.product.prodname_marketplace %}, you can't make changes to the plan. Instead, you'll need to remove the pricing plan. Customers who already purchased the removed pricing plan will continue to use it until they opt out and move onto a new pricing plan. For more on pricing plans, see "[{% data variables.product.prodname_marketplace %} pricing plans](/marketplace/selling-your-app/github-marketplace-pricing-plans/)." +Once you publish a pricing plan for an app that is already listed in {% data variables.product.prodname_marketplace %}, you can't make changes to the plan. Instead, you'll need to remove the pricing plan and create a new plan. Customers who already purchased the removed pricing plan will continue to use it until they opt out and move onto a new pricing plan. For more on pricing plans, see "[{% data variables.product.prodname_marketplace %} pricing plans](/marketplace/selling-your-app/github-marketplace-pricing-plans/)." Once you remove a pricing plan, users won't be able to purchase your app using that plan. Existing users on the removed pricing plan will continue to stay on the plan until they cancel their plan subscription. diff --git a/content/developers/github-marketplace/submitting-your-listing-for-publication.md b/content/developers/github-marketplace/submitting-your-listing-for-publication.md new file mode 100644 index 000000000000..b25c4580ae7e --- /dev/null +++ b/content/developers/github-marketplace/submitting-your-listing-for-publication.md @@ -0,0 +1,37 @@ +--- +title: Submitting your listing for publication +intro: 'You can submit your listing for the {% data variables.product.prodname_dotcom %} community to use.' +redirect_from: + - /marketplace/listing-on-github-marketplace/submitting-your-listing-for-review + - /developers/github-marketplace/submitting-your-listing-for-review +versions: + free-pro-team: '*' +--- + + + +Once you've completed the listing for your app, you'll see two buttons that allow you to request publication of the listing with or without verification. The **Request** button for "Publish without verification" is disabled if you have published any paid pricing plans in the listing. + + + +{% data reusables.marketplace.launch-with-free %} + +After you submit your listing for review, an onboarding expert will reach out to you with additional information. + +For an overview of the process for creating and submitting a listing, see "[About {% data variables.product.prodname_marketplace %}](/developers/github-marketplace/about-github-marketplace#publishing-an-app-to-github-marketplace)." + +### Prerequisites for publishing with verification + +Before you request verification of your listing, you'll need to integrate the {% data variables.product.prodname_marketplace %} billing flows and webhook into your app. For more information, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." + +If you've met the requirements for listing and you've integrated with the {% data variables.product.prodname_marketplace %} API, go ahead and submit your listing. For more information, see "[Requirements for listing an app](/developers/github-marketplace/requirements-for-listing-an-app)." + +{% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Transferring an app to an organization before you submit](#transferring-an-app-to-an-organization-before-you-submit)" below. + +### Transferring an app to an organization before you submit + +You cannot sell an app that's owned by a user account. You need to transfer the app to an organization that is already a verified creator, or that can request verification for a listing for the app. For details, see: + +1. "[Creating an organization from scratch](/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch)" + +1. "[Transferring ownership of a GitHub App](/developers/apps/transferring-ownership-of-a-github-app)" or "[Transferring ownership of an OAuth App](/developers/apps/transferring-ownership-of-an-oauth-app)" diff --git a/content/developers/github-marketplace/submitting-your-listing-for-review.md b/content/developers/github-marketplace/submitting-your-listing-for-review.md deleted file mode 100644 index 98a838e1f912..000000000000 --- a/content/developers/github-marketplace/submitting-your-listing-for-review.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Submitting your listing for review -intro: 'You can submit your listing as a verified or unverified app for the {% data variables.product.prodname_dotcom %} community to use.' -redirect_from: - - /marketplace/listing-on-github-marketplace/submitting-your-listing-for-review -versions: - free-pro-team: '*' ---- - - - -Once you've completed your app listing, you'll see two buttons that allow you to submit an unverified and verified app. The Publish without Verification **Request** button will not be available if you have published any paid pricing plans. - - - -{% data reusables.marketplace.launch-with-free %} - -Before you can submit a verified app, you'll need to integrate the {% data variables.product.prodname_marketplace %} billing flows and webhook into your existing app. See [Verified apps](/marketplace/#verified-apps) for the steps required to submit your app. - -If you've met the [requirements](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/) for a verified {% data variables.product.prodname_marketplace %} listing and you've integrated with the {% data variables.product.prodname_marketplace %} API, go ahead and submit your listing! - -After you submit your listing for review, the {% data variables.product.prodname_marketplace %} onboarding team will reach out to you with additional information. diff --git a/content/developers/github-marketplace/testing-your-app.md b/content/developers/github-marketplace/testing-your-app.md index 09e79b1a7a6b..577b6d624a35 100644 --- a/content/developers/github-marketplace/testing-your-app.md +++ b/content/developers/github-marketplace/testing-your-app.md @@ -1,6 +1,6 @@ --- title: Testing your app -intro: 'GitHub recommends testing your app with APIs and webhooks before submitting your listing to {% data variables.product.prodname_marketplace %} so you can provide an ideal experience for customers. Before the {% data variables.product.prodname_marketplace %} onboarding team approves your app, it must adequately handle the [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows).' +intro: 'GitHub recommends testing your app with APIs and webhooks before submitting your listing to {% data variables.product.prodname_marketplace %} so you can provide an ideal experience for customers. Before an onboarding expert approves your app, it must adequately handle the billing flows.' redirect_from: - /apps/marketplace/testing-apps-apis-and-webhooks/ - /apps/marketplace/integrating-with-the-github-marketplace-api/testing-github-marketplace-apps/ @@ -13,7 +13,7 @@ versions: ### Testing apps -You can use a [draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/) to simulate each of the [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows). A listing in the draft state means that it has not been submitted for approval. Any purchases you make using a draft {% data variables.product.prodname_marketplace %} listing will _not_ create real transactions, and GitHub will not charge your credit card. +You can use a draft {% data variables.product.prodname_marketplace %} listing to simulate each of the billing flows. A listing in the draft state means that it has not been submitted for approval. Any purchases you make using a draft {% data variables.product.prodname_marketplace %} listing will _not_ create real transactions, and GitHub will not charge your credit card. For more information, see "[Drafting a listing for your app](/developers/github-marketplace/drafting-a-listing-for-your-app)" and "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." #### Using a development app with a draft listing to test changes diff --git a/content/developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md b/content/developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md index e29643da16a5..96594bbc6146 100644 --- a/content/developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md +++ b/content/developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md @@ -1,6 +1,6 @@ --- title: Webhook events for the GitHub Marketplace API -intro: 'A {% data variables.product.prodname_marketplace %} app receives information about changes to a user''s plan from the Marketplace purchase event webhook. A Marketplace purchase event is triggered when a user purchases, cancels, or changes their payment plan. For details on how to respond to each of these types of events, see "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)."' +intro: 'A {% data variables.product.prodname_marketplace %} app receives information about changes to a user''s plan from the Marketplace purchase event webhook. A Marketplace purchase event is triggered when a user purchases, cancels, or changes their payment plan.' redirect_from: - /apps/marketplace/setting-up-github-marketplace-webhooks/about-webhook-payloads-for-a-github-marketplace-listing/ - /apps/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/ diff --git a/content/discussions/collaborating-with-your-community-using-discussions/about-discussions.md b/content/discussions/collaborating-with-your-community-using-discussions/about-discussions.md new file mode 100644 index 000000000000..09dde4a4554c --- /dev/null +++ b/content/discussions/collaborating-with-your-community-using-discussions/about-discussions.md @@ -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 + + + +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)" diff --git a/content/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions.md b/content/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions.md new file mode 100644 index 000000000000..b3ddfeed672a --- /dev/null +++ b/content/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions.md @@ -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)" + + + +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. +  +1. In the list of discussions, click the discussion you want to view. +  + +### 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)" diff --git a/content/discussions/collaborating-with-your-community-using-discussions/index.md b/content/discussions/collaborating-with-your-community-using-discussions/index.md new file mode 100644 index 000000000000..44aed03c8b9e --- /dev/null +++ b/content/discussions/collaborating-with-your-community-using-discussions/index.md @@ -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 %} + 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 new file mode 100644 index 000000000000..ed7012640586 --- /dev/null +++ b/content/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion.md @@ -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 %} diff --git a/content/discussions/guides/best-practices-for-community-conversations-on-github.md b/content/discussions/guides/best-practices-for-community-conversations-on-github.md new file mode 100644 index 000000000000..e4cc2321b6c6 --- /dev/null +++ b/content/discussions/guides/best-practices-for-community-conversations-on-github.md @@ -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)" diff --git a/content/discussions/guides/finding-discussions-across-multiple-repositories.md b/content/discussions/guides/finding-discussions-across-multiple-repositories.md new file mode 100644 index 000000000000..9b3d3d28734d --- /dev/null +++ b/content/discussions/guides/finding-discussions-across-multiple-repositories.md @@ -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**. +  +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)" diff --git a/content/discussions/guides/granting-higher-permissions-to-top-contributors.md b/content/discussions/guides/granting-higher-permissions-to-top-contributors.md new file mode 100644 index 000000000000..8ded0aaa3af8 --- /dev/null +++ b/content/discussions/guides/granting-higher-permissions-to-top-contributors.md @@ -0,0 +1,32 @@ +--- +title: Granting higher permissions to top contributors +intro: 'Repository administrators can promote any community member to a moderator and maintainer.' +versions: + free-pro-team: '*' +--- + +{% data reusables.discussions.beta %} + +### Introduction + +The most helpful contributors for the past 30 days are highlighted on the {% data variables.product.prodname_discussions %} dashboard, based on how many comments were marked as answers by other community members. Helpful contributors can help drive a healthy community and moderate and guide the community space in addition to maintainers. + +### Step 1: Audit your discussions top contributors + +{% data reusables.repositories.navigate-to-repo %} +{% data reusables.discussions.discussions-tab %} +1. Compare the list of contributors with their access permissions to see who qualifies to moderate the discussion. + +### Step 2: Review permission levels for discussions + +People with triage permissions for a repository can help moderate a project's discussions by marking comments as answers, locking discussions that are not longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. For more information, see "[Moderating discussions](/discussions/managing-discussions-for-your-community/moderating-discussions)." + +For more information about repository permission levels and {% data variables.product.prodname_discussions %}, see "[Repository permissions levels for an organization](/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization)." + +### Step 3: Change permissions levels for top contributors + +You can change a contributor's permission levels to give them more access to the tooling they need to moderate GitHub Discussions. To change a person's or team's permission levels, see "[Managing teams and people with access to your repository](/github/administering-a-repository/managing-teams-and-people-with-access-to-your-repository)." + +### Step 4: Notify community members of elevated access + +When you change a collaborators permission level, they will receive a notification for the change. diff --git a/content/discussions/guides/index.md b/content/discussions/guides/index.md new file mode 100644 index 000000000000..eb44c7cc0b4b --- /dev/null +++ b/content/discussions/guides/index.md @@ -0,0 +1,29 @@ +--- +title: Discussions guides +shortTitle: Guides +intro: 'Discover pathways to get started or learn best practices for participating or monitoring your community''s discussions.' +versions: + free-pro-team: '*' +--- + +{% data reusables.discussions.beta %} + +### Getting started with discussions + +{% link_in_list /about-discussions %} +{% link_in_list /best-practices-for-community-conversations-on-github %} +{% link_in_list /finding-discussions-across-multiple-repositories %} + +### Administering discussions + +{% link_in_list /granting-higher-permissions-to-top-contributors %} + + + diff --git a/content/discussions/index.md b/content/discussions/index.md new file mode 100644 index 000000000000..66dca4f270e2 --- /dev/null +++ b/content/discussions/index.md @@ -0,0 +1,55 @@ +--- +title: GitHub Discussions Documentation +beta_product: true +shortTitle: GitHub Discussions +intro: '{% data variables.product.prodname_discussions %} is a collaborative communication forum for the community around an open source project. Community members can ask and answer questions, share updates, have open-ended conversations, and follow along on decisions affecting the community''s way of working.' +introLinks: + quickstart: /discussions/quickstart +featuredLinks: + guides: + - /discussions/collaborating-with-your-community-using-discussions/about-discussions + - /discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion + - /discussions/managing-discussions-for-your-community/moderating-discussions + gettingStarted: + - /discussions/quickstart + guideCards: + - /discussions/collaborating-with-your-community-using-discussions/about-discussions + - /discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion + - /discussions/managing-discussions-for-your-community/moderating-discussions + popular: + - /discussions/guides/granting-higher-permissions-to-top-contributors + - /discussions/guides/best-practices-for-community-conversations-on-github + - /discussions/guides/finding-discussions-across-multiple-repositories + - /discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions + - /discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository +product_video: https://www.youtube-nocookie.com/embed/DbTWBP3_RbM +layout: product-landing +versions: + free-pro-team: '*' +--- + + + + + + + +{% assign discussionsCommunityExamples = site.data.variables.discussions_community_examples %} +{% if discussionsCommunityExamples %} +
+
+{% endif %}
diff --git a/content/discussions/managing-discussions-for-your-community/index.md b/content/discussions/managing-discussions-for-your-community/index.md
new file mode 100644
index 000000000000..8ccb2875b2fe
--- /dev/null
+++ b/content/discussions/managing-discussions-for-your-community/index.md
@@ -0,0 +1,13 @@
+---
+title: Managing discussions for your community
+shortTitle: Managing discussions
+intro: 'You can enable and configure discussions for your repository, and you can use tools on {% data variables.product.product_name %} to moderate conversations among community members.'
+versions:
+ free-pro-team: '*'
+---
+
+{% data reusables.discussions.beta %}
+
+{% link_in_list /managing-discussions-in-your-repository %}
+{% link_in_list /managing-categories-for-discussions-in-your-repository %}
+{% link_in_list /moderating-discussions %}
diff --git a/content/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository.md b/content/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository.md
new file mode 100644
index 000000000000..10a420e0db24
--- /dev/null
+++ b/content/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository.md
@@ -0,0 +1,64 @@
+---
+title: Managing categories for discussions in your repository
+intro: You can categorize the discussions in your repository to organize conversations for your community members, and you can choose a format for each category.
+permissions: Repository administrators and people with write or greater access to a repository can enable discussions in the repository.
+versions:
+ free-pro-team: '*'
+---
+
+{% data reusables.discussions.beta %}
+
+### About categories for discussions
+
+{% data reusables.discussions.about-discussions %} {% data reusables.discussions.about-categories-and-formats %}
+
+Each category must have a unique name and emoji pairing, and can be accompanied by a detailed description stating its purpose. Categories help maintainers organize how conversations are filed and are customizable to help distinguish categories that are Q&A or more open-ended conversations.{% data reusables.discussions.repository-category-limit %}
+
+For more information, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-categories-and-formats-for-discussions)."
+
+### Default categories
+
+| Category | Purpose | Type |
+| :- | :- | :- |
+| #️⃣ General | Anything and everything relevant to the project | Open-ended discussion |
+|💡Ideas | Ideas to change or improve the project | Open-ended discussion |
+| 🙏 Q&A | Questions for the community to answer, with a question/answer format | Question and Answer |
+| 🙌 Show and tell | Creations, experiments, or tests relevant to the project | Open-ended discussion |
+
+### Creating a category
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+{% data reusables.discussions.edit-categories %}
+1. Click **New category**.
+ 
+1. Edit the emoji, title, description, and discussion format for the category. For more information about discussion formats, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-categories-and-formats-for-discussions)."
+ 
+1. Click **Create**.
+ 
+
+### Editing a category
+
+You can edit a category to change the category's emoji, title, description, and discussion format.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+1. To the right of a category in the list, click {% octicon "pencil" aria-label="The pencil icon" %}.
+ 
+1. {% data reusables.discussions.edit-category-details %}
+ 
+1. Click **Save changes**.
+ 
+
+### Deleting a category
+
+When you delete a category, {% data variables.product.product_name %} will move all discussions in the deleted category to an existing category that you choose.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+1. To the right of a category in the list, click {% octicon "trash" aria-label="The trash icon" %}.
+ 
+1. Use the drop-down menu, and choose a new category for any discussions in the category you're deleting.
+ 
+1. Click **Delete & Move**.
+ 
diff --git a/content/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository.md b/content/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository.md
new file mode 100644
index 000000000000..28251d047821
--- /dev/null
+++ b/content/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository.md
@@ -0,0 +1,108 @@
+---
+title: Managing discussions in your repository
+intro: You can categorize, spotlight, transfer, or delete the discussions in a repository.
+permissions: Repository administrators and people with write or greater access to a repository can manage discussions in the repository.
+versions:
+ free-pro-team: '*'
+---
+
+{% data reusables.discussions.beta %}
+
+### About management of discussions
+
+{% data reusables.discussions.about-discussions %} For more information about discussions, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)."
+
+Organization owners can choose the permissions required to create a discussion for repositories owned by the organization. For more information, see "[Managing discussion creation for repositories in your organization](/github/setting-up-and-managing-organizations-and-teams/managing-discussion-creation-for-repositories-in-your-organization)."
+
+As a discussions maintainer, you can create community resources to encourage discussions that are aligned with the overall project goal and maintain a friendly open forum for collaborators. Creating a code of conduct or contribution guidelines for collaborators to follow will help facilitate a collaborative and productive forum. For more information on creating community resources, see "[Adding a code of conduct to your project](/github/building-a-strong-community/adding-a-code-of-conduct-to-your-project)," and "[Setting guidelines for repository contributors](/github/building-a-strong-community/setting-guidelines-for-repository-contributors)."
+
+For more information on facilitating a healthy discussion, see "[Moderating comments and conversations](/github/building-a-strong-community/moderating-comments-and-conversations)."
+
+### Prerequisites
+
+To manage discussions in a repository, discussions must be enabled 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)."
+
+### Changing the category for a discussion
+
+You can categorize discussions to help community members find related discussions. For more information, see "[Managing categories for discussions in your repository](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository)" article.
+
+You can also move a discussion to a different category.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+{% data reusables.discussions.click-discussion-in-list %}
+1. In the right sidebar, click {% octicon "pencil" aria-label="The pencil icon" %} **Edit pinned discussion**.
+ 
+
+### Pinning a discussion
+
+You can pin up to four important discussions above the list of discussions for the repository.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+{% data reusables.discussions.click-discussion-in-list %}
+1. In the right sidebar, click {% octicon "pin" aria-label="The pin icon" %} **Pin discussion**.
+ 
+1. Optionally, customize the look of the pinned discussion.
+ 
+1. Click **Pin discussion**.
+ 
+
+### Editing a pinned discussion
+
+Editing a pinned discussion will not change the discussion's category. For more information, see "[Managing categories for discussions in your repository](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository)."
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+{% data reusables.discussions.click-discussion-in-list %}
+1. In the right sidebar, click {% octicon "pencil" aria-label="The pencil icon" %} **Edit pinned discussion**.
+ 
+1. Customize the look of the pinned discussion.
+ 
+1. Click **Pin discussion**.
+ 
+
+### Unpinning a discussion
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+{% data reusables.discussions.click-discussion-in-list %}
+1. In the right sidebar, click {% octicon "pin" aria-label="The pin icon" %} **Unpin discussion**.
+ 
+1. Read the warning, then click **Unpin discussion**.
+ 
+
+### Transferring a discussion
+
+To transfer a discussion, you must have permissions to create discussions in the repository where you want to transfer the discussion.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+{% data reusables.discussions.click-discussion-in-list %}
+1. In the right sidebar, click {% octicon "arrow-right" aria-label="The right arrow icon" %} **Transfer discussion**.
+ 
+1. Select the **Choose a repository** drop-down, and click the repository you want to transfer the discussion to.
+ 
+1. Click **Transfer discussion**.
+ 
+
+### Deleting a discussion
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+{% data reusables.discussions.click-discussion-in-list %}
+1. In the right sidebar, click {% octicon "trash" aria-label="The trash arrow icon" %} **Delete discussion**.
+ 
+1. Read the warning, then click **Delete this discussion**.
+ 
+
+### Converting issues based on labels
+
+You can convert all issues with the same label to discussions in bulk. Future issues with this label will also automatically convert to the discussion and category you configure.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-issues %}
+{% data reusables.project-management.labels %}
+1. Next to the label you want to convert to issues, click **Convert issues**.
+1. Select the **Choose a category** drop-down menu, and click a category for your discussion.
+1. Click **I understand, convert this issue to a discussion**.
diff --git a/content/discussions/managing-discussions-for-your-community/moderating-discussions.md b/content/discussions/managing-discussions-for-your-community/moderating-discussions.md
new file mode 100644
index 000000000000..802e325e3d2e
--- /dev/null
+++ b/content/discussions/managing-discussions-for-your-community/moderating-discussions.md
@@ -0,0 +1,40 @@
+---
+title: Moderating discussions
+intro: 'You can promote healthy collaboration by marking comments as answers, locking or unlocking discussions, and converting issues to discussions. and editing or deleting comments, discussions, and categories that don''t align with your community''s code of conduct to discussions.'
+permissions: People with triage access to a repository can moderate discussions in the repository.
+versions:
+ free-pro-team: '*'
+---
+
+{% data reusables.discussions.beta %}
+
+### About moderating discussions
+
+{% data reusables.discussions.about-discussions %} If you have triage permissions for a repository, you can help moderate a project's discussions by marking comments as answers, locking discussions that are not longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development.
+
+### Marking a comment as an answer
+
+{% data reusables.discussions.marking-a-comment-as-an-answer %}
+
+### Locking discussions
+
+It's appropriate to lock a conversation when the entire conversation is not constructive or violates your community's code of conduct or {% data variables.product.prodname_dotcom %}'s [Community Guidelines](/github/site-policy/github-community-guidelines). You can also lock a conversation to prevent comments on a discussion you want to use as an announcement to the community. When you lock a conversation, people with write access to the repository will still be able to comment on the discussion.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+1. In the list of discussions, click the discussion you want to lock.
+ 
+1. In the right margin of a discussion, click **Lock conversation**.
+1. Read the information about locking conversations and click **Lock conversation on this discussion**.
+1. When you're ready to unlock the conversation, click **Unlock conversation**, then click **Unlock conversation on this discussion**.
+
+### Converting an issue to a discussion
+
+When you convert an issue to a discussion, the discussion is automatically created using the content from the issue. People with write access to a repository can bulk convert issues based on labels. For more information, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository)."
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-issues %}
+1. In the list of issues, click the issue you'd like to convert.
+1. In the right margin of an issue, click **Convert to discussion**.
+1. Select the **Choose a category** drop-down menu, and click a category for your discussion.
+1. Click **I understand, convert this issue to a discussion**.
diff --git a/content/discussions/quickstart.md b/content/discussions/quickstart.md
new file mode 100644
index 000000000000..2bdf5404256f
--- /dev/null
+++ b/content/discussions/quickstart.md
@@ -0,0 +1,60 @@
+---
+title: Quickstart for GitHub Discussions
+intro: 'Enable {% data variables.product.prodname_discussions %} on an existing repository and start conversations with your community.'
+allowTitleToDifferFromFilename: true
+versions:
+ free-pro-team: '*'
+---
+
+{% data reusables.discussions.beta %}
+
+### Introduction
+
+{% data variables.product.prodname_discussions %} is a collaborative communication forum for the community around an open source project. Discussions are for conversations that need to be transparent and accessible but do not need to be tracked on a project board and are not related to code, unlike issues. Discussions enable fluid, open conversation in a public forum.
+
+Discussions give a space for more collaborative conversations by connecting and giving a more centralized area to connect and find information.
+
+### Enabling {% data variables.product.prodname_discussions %} on your repository
+
+Repository owners and people with write access can enable {% data variables.product.prodname_discussions %} for a community on their public repositories.
+
+When you first enable a {% data variables.product.prodname_discussions %}, you will be invited to configure a welcome post.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+1. Under "Features", click **Set up discussions**.
+ 
+1. Under "Start a new discussion," edit the template to align with the resources and tone you want to set for your community.
+1. Click **Start discussion**.
+ 
+
+### Welcoming contributions to your discussions
+
+You can welcome your community and introduce a new way to communicate in a repository by creating a welcome post and pin the post to your {% data variables.product.prodname_discussions %} page. Pinning and locking discussions helps people know that a post is meant as an announcement. You can use announcements as a way to link people to more resources and offer guidance for opening discussions in your community. For more information about pinning a discussion, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository#pinning-a-discussion)."
+
+
+### Setting up community guidelines for contributors
+
+You can set contributing guidelines to encourage collaborators to have meaningful, useful conversations that are relevant to the repository. You can also update the repository's README to communicate expectations on when collaborators should open an issue or discussion.
+
+For more information about providing guidelines for your project, see "[Adding a code of conduct to your project](/github/building-a-strong-community/adding-a-code-of-conduct-to-your-project)" and "[Setting up your project for healthy contributions](/github/building-a-strong-community/setting-up-your-project-for-healthy-contributions)."
+
+### Creating a new discussion
+
+Anyone with access to a repository can create a discussion.
+
+{% data reusables.discussions.starting-a-discussion %}
+
+### Organizing discussions into relevant categories
+
+Repository owners and people with write access can create new categories to keep discussions organized. Collaborators participating and creating new discussions can group discussions into the most relevant existing categories. Discussions can also be recategorized after they are created. For more information, see "[Managing categories for discussions in your repository](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository)"
+
+### Promoting healthy conversations
+
+People with write permissions for a repository can help surface important conversations by pinning discussions, deleting discussions that are no longer useful or are damaging to the community, and transferring discussions to more relevant repositories owned by the organization. For more information, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository)."
+
+People with triage permissions for a repository can help moderate a project's discussions by marking comments as answers, locking discussions that are not longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. For more information, see "[Moderating discussions](/discussions/managing-discussions-for-your-community/moderating-discussions)."
+
+### Next steps
+
+Once there is a clear path to scope work out and move an idea from concept to reality, you can create an issue and start tracking your progress. For more information on creating an issue from a discussion, see "[Moderating discussions](/discussions/managing-discussions-for-your-community/moderating-discussions)."
diff --git a/content/education/guides.md b/content/education/guides.md
new file mode 100644
index 000000000000..0265b5363331
--- /dev/null
+++ b/content/education/guides.md
@@ -0,0 +1,45 @@
+---
+title: Guides for GitHub Education
+intro: 'These guides for {% data variables.product.prodname_education %} help you teach and learn both {% data variables.product.product_name %} and software development.'
+allowTitleToDifferFromFilename: true
+versions:
+ free-pro-team: '*'
+---
+
+### Get started with {% data variables.product.product_name %}
+
+Teachers, students, and researchers can use tools from {% data variables.product.product_name %} to enrich a software development curriculum and develop real-world collaboration skills.
+
+- [Sign up for a new {% data variables.product.prodname_dotcom %} account](/github/getting-started-with-github/signing-up-for-a-new-github-account)
+- [Git and {% data variables.product.prodname_dotcom %} quickstart ](/github/getting-started-with-github/quickstart)
+- [Apply for an educator or researcher discount](/education/teach-and-learn-with-github-education/apply-for-an-educator-or-researcher-discount)
+- [Apply for a student developer pack](/education/teach-and-learn-with-github-education/apply-for-a-student-developer-pack)
+
+### Run a software development course with {% data variables.product.company_short %}
+
+Administer a classroom, assign and review work from your students, and teach the new generation of software developers with {% data variables.product.prodname_classroom %}.
+
+- [Basics of setting up {% data variables.product.prodname_classroom %} ](/education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom)
+- [Manage classrooms](/education/manage-coursework-with-github-classroom/manage-classrooms)
+- [Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)
+- [Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)
+- [Create an assignment from a template repository](/education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository)
+- [Leave feedback with pull requests](/education/manage-coursework-with-github-classroom/leave-feedback-with-pull-requests)
+- [Use autograding](/education/manage-coursework-with-github-classroom/use-autograding)
+
+### Learn to develop software
+
+Incorporate {% data variables.product.prodname_dotcom %} into your education, and use the same tools as the professionals.
+
+- [Git and {% data variables.product.prodname_dotcom %} learning resources](/github/getting-started-with-github/git-and-github-learning-resources)
+- [Use {% data variables.product.prodname_dotcom %} for your schoolwork](/education/teach-and-learn-with-github-education/use-github-for-your-schoolwork)
+- [Try {% data variables.product.prodname_desktop %}](/desktop)
+- [Try {% data variables.product.prodname_cli %}](/github/getting-started-with-github/github-cli)
+
+### Contribute to the community
+
+Participate in the community, get training from {% data variables.product.company_short %}, and learn or teach new skills.
+
+- [{% data variables.product.prodname_education_community %}](https://education.github.community)
+- [About Campus Experts](/education/teach-and-learn-with-github-education/about-campus-experts)
+- [About Campus Advisors](/education/teach-and-learn-with-github-education/about-campus-advisors)
diff --git a/content/education/index.md b/content/education/index.md
new file mode 100644
index 000000000000..fee80a351ce7
--- /dev/null
+++ b/content/education/index.md
@@ -0,0 +1,43 @@
+---
+title: GitHub Education Documentation
+shortTitle: Education
+intro: "{% data variables.product.prodname_education %} helps you teach or learn software development with the tools and support of {% data variables.product.company_short %}'s platform and community."
+introLinks:
+ quickstart: /education/quickstart
+featuredLinks:
+ guides:
+ - /education/teach-and-learn-with-github-education/apply-for-a-student-developer-pack
+ - /education/teach-and-learn-with-github-education/apply-for-an-educator-or-researcher-discount
+ - /education/teach-and-learn-with-github-education/use-github-at-your-educational-institution
+ guideCards:
+ - /github/getting-started-with-github/signing-up-for-a-new-github-account
+ - /github/getting-started-with-github/git-and-github-learning-resources
+ - /education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom
+ popular:
+ - /education/teach-and-learn-with-github-education/use-github-for-your-schoolwork
+ - /education/teach-and-learn-with-github-education/use-github-in-your-classroom-and-research
+ - /desktop
+ - /github/getting-started-with-github/github-cli
+ - /education/manage-coursework-with-github-classroom/teach-with-github-classroom
+
+changelog:
+ - title: 'Try something new at Local Hack Day: Learn'
+ date: '2020-10-15'
+ href: https://github.blog/2020-10-15-try-something-new-at-local-hack-day-learn/
+ - title: 'Remote Education: Creating community through shared experiences'
+ date: '2020-09-24'
+ href: https://github.blog/2020-09-24-remote-education-creating-community-through-shared-experiences/
+ - title: 'Remote Education: A series of best practices for online campus communities'
+ date: '2020-09-10'
+ href: https://github.blog/2020-09-10-remote-education-a-series-of-best-practices-for-online-campus-communities/
+ - title: Welcome to the inaugural class of MLH Fellows
+ date: '2020-06-24'
+ href: https://github.blog/2020-06-24-welcome-to-the-inaugural-class-of-mlh-fellows/
+
+layout: product-landing
+versions:
+ free-pro-team: '*'
+---
+
+
+
diff --git a/content/education/manage-coursework-with-github-classroom/about-using-makecode-arcade-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/about-using-makecode-arcade-with-github-classroom.md
new file mode 100644
index 000000000000..a608267c1c95
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/about-using-makecode-arcade-with-github-classroom.md
@@ -0,0 +1,31 @@
+---
+title: About using MakeCode Arcade with GitHub Classroom
+shortTitle: About using MakeCode Arcade
+intro: You can configure MakeCode Arcade as the online IDE for assignments in {% data variables.product.prodname_classroom %}.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/student-experience-makecode
+---
+
+### About MakeCode Arcade
+
+MakeCode Arcade is an online integrated development environment (IDE) for developing retro arcade games using drag-and-drop block programming and JavaScript. Students can write, edit, run, test, and debug code in a browser with MakeCode Arcade. For more information about online IDEs and {% data variables.product.prodname_classroom %}, see "[Integrate {% data variables.product.prodname_classroom %} with an online IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide)."
+
+{% data reusables.classroom.readme-contains-button-for-online-ide %}
+
+The first time the student clicks the button to visit MakeCode Arcade, the student must sign into MakeCode Arcade with {% data variables.product.product_name %} credentials. After signing in, the student will have access to a development environment containing the code from the assignment repository, fully configured on MakeCode Arcade.
+
+For more information about working on MakeCode Arcade, see the [MakeCode Arcade Tour](https://arcade.makecode.com/ide-tour) and [documentation](https://arcade.makecode.com/docs) on the MakeCode Arcade website.
+
+MakeCode Arcade does not support multiplayer-editing for group assignments. Instead, students can collaborate with Git and {% data variables.product.product_name %} features like branches and pull requests.
+
+### About submission of assignments with MakeCode Arcade
+
+By default, MakeCode Arcade is configured to push to the assignment repository on {% data variables.product.product_location %}. After making progress on an assignment with MakeCode Arcade, students should push changes to {% data variables.product.product_location %} using the {% octicon "mark-github" aria-label="The GitHub mark" %}{% octicon "arrow-up" aria-label="The up arrow icon" %} button at the bottom of the screen.
+
+
+
+### Further reading
+
+- "[About READMEs](/github/creating-cloning-and-archiving-repositories/about-readmes)"
diff --git a/content/education/manage-coursework-with-github-classroom/about-using-replit-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/about-using-replit-with-github-classroom.md
new file mode 100644
index 000000000000..5c4dcdb949e6
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/about-using-replit-with-github-classroom.md
@@ -0,0 +1,33 @@
+---
+title: About using Repl.it with GitHub Classroom
+shortTitle: About using Repl.it
+intro: You can configure Repl.it as the online integrated development environment (IDE) for assignments in {% data variables.product.prodname_classroom %}.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/student-experience-replit
+---
+
+### About Repl.it
+
+Repl.it is an online integrated development environment (IDE) that supports multiple programming languages. Students can write, edit, run, test, and debug code in a browser with Repl.it. For more information about online IDEs and {% data variables.product.prodname_classroom %}, see "[Integrate {% data variables.product.prodname_classroom %} with an online IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide)."
+
+{% data reusables.classroom.readme-contains-button-for-online-ide %}
+
+The first time the student clicks the button to visit Repl.it, the student must sign into Repl.it with {% data variables.product.product_name %} credentials. After signing in, the student will have access to a development environment containing the code from the assignment repository, fully configured on Repl.it.
+
+For more information about working on Repl.it, see the [Repl.it Quickstart Guide](https://docs.repl.it/misc/quick-start#the-repl-environment).
+
+For group assignments, students can use Repl.it Multiplayer to work collaboratively. For more information, see the [Repl.it Multiplayer](https://repl.it/site/multiplayer) website.
+
+### About submission of assignments with Repl.it
+
+By default, Repl.it is configured to push to the assignment repository on {% data variables.product.product_location %}. After making progress on an assignment with Repl.it, students should push changes to {% data variables.product.product_location %} using the version control functionality in the left sidebar.
+
+
+
+For more information about using Git on Repl.it, see the [Repl.it + Git Tutorial](https://repl.it/talk/learn/Replit-Git-Tutorial/23331) on the Repl.it website.
+
+### Further reading
+
+- "[About READMEs](/github/creating-cloning-and-archiving-repositories/about-readmes)"
diff --git a/content/education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom.md b/content/education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom.md
new file mode 100644
index 000000000000..872bc8fac882
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom.md
@@ -0,0 +1,33 @@
+---
+title: Basics of setting up GitHub Classroom
+shortTitle: '{% data variables.product.prodname_classroom %} basics'
+intro: Learn how to set up your classroom, manage assignments, and configure time-saving automation.
+versions:
+ free-pro-team: '*'
+---
+
+### Videos about {% data variables.product.prodname_classroom %}
+
+You can watch a series of short video tutorials about the configuration and use of {% data variables.product.prodname_classroom %}. To watch all videos as part of a continuous playlist, see the [{% data variables.product.prodname_classroom %} Getting Started Guide](https://www.youtube.com/playlist?list=PLIRjfNq867bewk3ZGV6Z7a16YDNRCpK3u) on YouTube.
+
+For more information about terminology for {% data variables.product.prodname_classroom %}, see "[Glossary](/education/manage-coursework-with-github-classroom/glossary)".
+
+1. Getting started {% octicon "link-external" aria-label="The external link icon" %}
+2. Adding your student roster {% octicon "link-external" aria-label="The external link icon" %}
+3. Creating assignments
+ - Creating an assignment using a {% data variables.product.prodname_dotcom %} repository {% octicon "link-external" aria-label="The external link icon" %}
+ - Creating an assignment using Microsoft MakeCode as your online IDE {% octicon "link-external" aria-label="The external link icon" %}
+ - Creating an assignment using Repl.it as your online IDE {% octicon "link-external" aria-label="The external link icon" %}
+4. How students complete assignments {% octicon "link-external" aria-label="The external link icon" %}
+5. How teachers review assignments {% octicon "link-external" aria-label="The external link icon" %}
+6. Creating group assignments {% octicon "link-external" aria-label="The external link icon" %}
+7. Next steps to get started {% octicon "link-external" aria-label="The external link icon" %}
+8. {% data variables.product.prodname_dotcom %} Teacher Toolbox {% octicon "link-external" aria-label="The external link icon" %}
+
+### Next steps
+
+For more information about teaching with {% data variables.product.prodname_classroom %}, see "[Teach with {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/teach-with-github-classroom)."
+
+### Further reading
+
+- "[Teach and learn with {% data variables.product.prodname_education %}](/education/teach-and-learn-with-github-education)"
diff --git a/content/education/manage-coursework-with-github-classroom/configure-default-settings-for-assignment-repositories.md b/content/education/manage-coursework-with-github-classroom/configure-default-settings-for-assignment-repositories.md
new file mode 100644
index 000000000000..a0ff56492ed4
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/configure-default-settings-for-assignment-repositories.md
@@ -0,0 +1,51 @@
+---
+title: Configure default settings for assignment repositories
+shortTitle: Configure defaults for assignment repositories
+intro: You can use the Probot Settings app to configure the default settings for repositories that {% data variables.product.prodname_classroom %} creates for an assignment.
+permissions: Organization owners can configure default settings for assignment repositories by installing a {% data variables.product.prodname_github_app %} for the organization.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/probot-settings
+---
+
+### About configuration of defaults for assignment repositories
+
+{% data variables.product.prodname_classroom %} creates a repository that belongs for each student or team that accepts an assignment. The repository belongs to the organization that you use for {% data variables.product.prodname_classroom %}. Assignment repositories can be empty, or you can use a template repository. For more information, see "[Create an assignment from a template repository](/education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository)."
+
+{% data reusables.classroom.you-may-want-to-predefine-repository-settings %}
+
+With the Probot Settings app, you can create a file named _.github/settings.yml_ in a repository that contains a list of settings for the repository, and then install a {% data variables.product.prodname_github_app %} for your organization that automatically applies the settings to the repository.
+
+You can include _.github/settings.yml_ in a template repository that you use for an assignment in {% data variables.product.prodname_classroom %}. When an individual or team accepts the assignment, {% data variables.product.prodname_classroom %} creates the assignment repository, and the Settings app automatically applies the settings from _.github/settings.yml_.
+
+Probot is a a project, framework, and collection of free apps to automate {% data variables.product.product_name %}. A Probot app can listen to repository events, like the creation of new commits, comments, and issues, and automatically respond to the event.
+
+For more information, see the [Probot website](https://probot.github.io) and the [Settings app website](https://probot.github.io/apps/settings/). For more information about {% data variables.product.prodname_github_apps %}, see "[About apps](/developers/apps/about-apps)."
+
+### Adding the Settings app to your organization
+
+After you install the Probot Settings app for your organization, the app will apply the settings that you define in _.github/settings.yml_ for any repository in your organization, including new assignment repositories that {% data variables.product.prodname_classroom %} creates.
+
+1. Navigate to the [Settings app page](https://github.com/apps/settings).
+1. Click **Install**, then click the organization that you use for {% data variables.product.prodname_classroom %}. Provide the app full access to all repositories owned by the organization.
+ 
+
+### Configuring default settings for an assignment repository
+
+1. Create a template repository that contains a _.github/settings.yml_ file. For a complete list of settings, see the [README](https://github.com/probot/settings#github-settings) for the `probot/settings` repository. For more information about using a template repository for starter code in {% data variables.product.prodname_classroom %}, see "[Create an assignment from a template repository](/education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository)."
+
+ {% warning %}
+
+ **Warning:** Do not define `collaborators` in the _.github/settings.yml_ file for your template repository. {% data variables.product.prodname_classroom %} automatically grants teachers and teaching assistants access to assignment repositories.
+
+ {% endwarning %}
+
+1. Create an assignment using the template repository containing _.github/settings.yml_ as the starter code. {% data reusables.classroom.for-more-information-about-assignment-creation %}
+
+The Probot Settings app for your organization will now apply the settings you define in _.github/settings.yml_ within the template repository to every assignment repository that {% data reusables.classroom.you-may-want-to-predefine-repository-settings %} creates for a student or team.
+
+### Further reading
+
+- [Probot apps](https://probot.github.io/apps/)
+- [Probot documentation](https://probot.github.io/docs/)
diff --git a/content/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom.md b/content/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom.md
new file mode 100644
index 000000000000..0ed3baed4f35
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom.md
@@ -0,0 +1,142 @@
+---
+title: Connect a learning management system to GitHub Classroom
+intro: You can configure an LTI-compliant learning management system (LMS) to connect to {% data variables.product.prodname_classroom %} so that you can import a roster for your classroom.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/configuring-a-learning-management-system-for-github-classroom
+ - /education/manage-coursework-with-github-classroom/connect-to-lms
+ - /education/manage-coursework-with-github-classroom/generate-lms-credentials
+ - /education/manage-coursework-with-github-classroom/setup-canvas
+ - /education/manage-coursework-with-github-classroom/setup-generic-lms
+ - /education/manage-coursework-with-github-classroom/setup-moodle
+---
+
+### About configuration of your LMS
+
+You can connect a learning management system (LMS) to {% data variables.product.prodname_classroom %}, and {% data variables.product.prodname_classroom %} can import a roster of student identifiers from the LMS. To connect your LMS to {% data variables.product.prodname_classroom %}, you must enter configuration credentials for {% data variables.product.prodname_classroom %} in your LMS.
+
+### Prerequisites
+
+To configure an LMS to connect to {% data variables.product.prodname_classroom %}, you must first create a classroom. For more information, see "[Manage classrooms](/education/manage-coursework-with-github-classroom/manage-classrooms#creating-a-classroom)."
+
+### Supported LMSes
+
+{% data variables.product.prodname_classroom %} supports import of roster data from LMSes that implement Learning Tools Interoperability (LTI) standards.
+
+- LTI version 1.0 and/or 1.1
+- LTI Names and Roles Provisioning 1.X
+
+Using LTI helps keep your information safe and secure. LTI is an industry-standard protocol and GitHub Classroom's use of LTI is certified by the Instructional Management System (IMS) Global Learning Consortium. For more information, see [Learning Tools Interoperability](https://www.imsglobal.org/activity/learning-tools-interoperability) and [About IMS Global Learning Consortium](http://www.imsglobal.org/aboutims.html) on the IMS Global Learning Consortium website.
+
+{% data variables.product.company_short %} has tested import of roster data from the following LMSes into {% data variables.product.prodname_classroom %}.
+
+- Canvas
+- Google Classroom
+- Moodle
+- Sakai
+
+Currently, {% data variables.product.prodname_classroom %} doesn't support import of roster data from Blackboard or Brightspace
+
+### Generating configuration credentials for your classroom
+
+{% data reusables.classroom.sign-into-github-classroom %}
+{% data reusables.classroom.click-classroom-in-list %}
+{% data reusables.classroom.click-students %}
+1. If your classroom already has a roster, you can either update the roster or delete the roster and create a new roster.
+ - For more information about deleting and creating a roster, see "[Deleting a roster for a classroom](/education/manage-coursework-with-github-classroom/manage-classrooms#deleting-a-roster-for-a-classroom)" and "[Creating a roster for your classroom](/education/manage-coursework-with-github-classroom/manage-classrooms#creating-a-roster-for-your-classroom)."
+ - For more information about updating a roster, see "[Adding students to the roster for your classroom](/education/manage-coursework-with-github-classroom/manage-classrooms#adding-students-to-the-roster-for-your-classroom)."
+1. In the list of LMSes, click your LMS. If your LMS is not supported, click **Other LMS**.
+ 
+1. Read about connecting your LMS, then click **Connect to _LMS_**.
+1. Copy the "Consumer Key", "Shared Secret", and "Launch URL" for the connection to the classroom.
+ 
+
+### Configuring a generic LMS
+
+You must configure the privacy settings for your LMS to allow external tools to receive roster information.
+
+1. Navigate to your LMS.
+1. Configure an external tool.
+1. Provide the configuration credentials you generated in {% data variables.product.prodname_classroom %}.
+ - Consumer key
+ - Shared secret
+ - Launch URL (sometimes called "tool URL" or similar)
+
+### Configuring Canvas
+
+You can configure {% data variables.product.prodname_classroom %} as an external app for Canvas to import roster data into your classroom. For more information about Canvas, see the [Canvas website](https://www.instructure.com/canvas/).
+
+1. Sign into [Canvas](https://www.instructure.com/canvas/#login).
+1. Select the Canvas course to integrate with {% data variables.product.prodname_classroom %}.
+1. In the left sidebar, click **Settings**.
+1. Click the **Apps** tab.
+1. Click **View app configurations**.
+1. Click **+App**.
+1. Select the **Configuration Type** drop-down menu, and click **By URL**.
+1. Paste the configuration credentials from {% data variables.product.prodname_classroom %}. For more information, see "[Generating configuration credentials for your classroom](#generating-configuration-credentials-for-your-classroom)."
+
+ | Field in Canvas app configuration | Value or setting |
+ | :- | :- |
+ | **Consumer Key** | Consumer key from {% data variables.product.prodname_classroom %} |
+ | **Shared Secret** | Shared secret from {% data variables.product.prodname_classroom %} |
+ | **Allow this tool to access the IMS Names and Role Provisioning Service** | Enabled |
+ | **Configuration URL** | Launch URL from {% data variables.product.prodname_classroom %} |
+
+ {% note %}
+
+ **Note**: If you don't see a checkbox in Canvas labeled "Allow this tool to access the IMS Names and Role Provisioning Service", then your Canvas administrator must contact Canvas support to enable membership service configuration for your Canvas account. Without enabling this feature, you won't be able to sync the roster from Canvas. For more information, see [How do I contact Canvas Support?](https://community.canvaslms.com/t5/Canvas-Basics-Guide/How-do-I-contact-Canvas-Support/ta-p/389767) on the Canvas website.
+
+ {% endnote %}
+
+1. Click **Submit**.
+1. In the left sidebar, click **Home**.
+1. To prompt Canvas to send a confirmation email, in the left sidebar, click **GitHub Classroom**. Follow the instructions in the email to finish linking {% data variables.product.prodname_classroom %}.
+
+### Configuring Moodle
+
+You can configure {% data variables.product.prodname_classroom %} as an activity for Moodle to import roster data into your classroom. For more information about Moodle, see the [Moodle website](https://moodle.org).
+
+You must be using Moodle version 3.0 or greater.
+
+1. Sign into [Moodle](https://moodle.org/login/index.php).
+1. Select the Moodle course to integrate with {% data variables.product.prodname_classroom %}.
+1. Click **Turn editing on**.
+1. Wherever you'd like {% data variables.product.prodname_classroom %} to be available in Moodle, click **Add an activity or resource**.
+1. Choose **External tool** and click **Add**.
+1. In the "Activity name" field, type "GitHub Classroom".
+1. In the **Preconfigured tool** field, to the right of the drop-down menu, click **+**.
+1. Under "External tool configuration", paste the configuration credentials from {% data variables.product.prodname_classroom %}. For more information, see "[Generating configuration credentials for your classroom](#generating-configuration-credentials-for-your-classroom)."
+
+ | Field in Moodle app configuration | Value or setting |
+ | :- | :- |
+ | **Tool name** | {% data variables.product.prodname_classroom %} - _YOUR CLASSROOM NAME_Communities using discussions
+ +
+ {% render 'discussions-community-card' for discussionsCommunityExamples as example %}
+
+ {% if discussionsCommunityExamples.length > 6 %}
+
+ {% endif %}
+
+
+{% octicon "search" width="24" %}
+ Sorry, there is no result for
+It looks like we don't have an example that fits your filter.
Try another filter or add your code example
**Note**: You can use any name, but we suggest this value for clarity. | + | **Tool URL** | Launch URL from {% data variables.product.prodname_classroom %} | + | **LTI version** | LTI 1.0/1.1 | + | **Default launch container** | New window | + | **Consumer key** | Consumer key from {% data variables.product.prodname_classroom %} | + | **Shared secret** | Shared secret from {% data variables.product.prodname_classroom %} | + +1. Scroll to and click **Services**. +1. To the right of "IMS LTI Names and Role Provisioning", select the drop-down menu and click **Use this service to retrieve members' information as per privacy settings**. +1. Scroll to and click **Privacy**. +1. To the right of **Share launcher's name with tool** and **Share launcher's email with tool**, select the drop-down menus to click **Always**. +1. At the bottom of the page, click **Save changes**. +1. In the **Preconfigure tool** menu, click **GitHub Classroom - _YOUR CLASSROOM NAME_**. +1. Under "Common module settings", to the right of "Availability", select the drop-down menu and click **Hide from students**. +1. At the bottom of the page, click **Save and return to course**. +1. Navigate to anywhere you chose to display {% data variables.product.prodname_classroom %}, and click the {% data variables.product.prodname_classroom %} activity. + +### Importing a roster from your LMS + +For more information about importing the roster from your LMS into {% data variables.product.prodname_classroom %}, see "[Manage classrooms](/education/manage-coursework-with-github-classroom/manage-classrooms#creating-a-roster-for-your-classroom)." + +### Disconnecting your LMS + +{% data reusables.classroom.sign-into-github-classroom %} +{% data reusables.classroom.click-classroom-in-list %} +{% data reusables.classroom.click-settings %} +1. Under "Connect to a learning management system (LMS)", click **Connection Settings**. +  +1. Under "Delete Connection to your learning management system", click **Disconnect from your learning management system**. +  diff --git a/content/education/manage-coursework-with-github-classroom/create-a-group-assignment.md b/content/education/manage-coursework-with-github-classroom/create-a-group-assignment.md new file mode 100644 index 000000000000..2b42b006f8d6 --- /dev/null +++ b/content/education/manage-coursework-with-github-classroom/create-a-group-assignment.md @@ -0,0 +1,145 @@ +--- +title: Create a group assignment +intro: 'You can create a collaborative assignment for teams of students who participate in your course.' +versions: + free-pro-team: '*' +redirect_from: + - /education/manage-coursework-with-github-classroom/create-group-assignments +--- + +### About group assignments + +{% data reusables.classroom.assignments-group-definition %} Students can work together on a group assignment in a shared repository, like a team of professional developers. + +When a student accepts a group assignment, the student can create a new team or join an existing team. {% data variables.product.prodname_classroom %} saves the teams for an assignment as a set. You can name the set of teams for a specific assignment when you create the assignment, and you can reuse that set of teams for a later assignment. + +{% data reusables.classroom.classroom-creates-group-repositories %} + +{% data reusables.classroom.about-assignments %} + +You can decide how many teams one assignment can have, and how many members each team can have. Each team that a student creates for an assignment is a team within your organization on {% data variables.product.product_name %}. The visibility of the team is secret. Teams that you create on {% data variables.product.product_name %} will not appear in {% data variables.product.prodname_classroom %}. For more information, see "[About teams](/github/setting-up-and-managing-organizations-and-teams/about-teams)." + +For a video demonstration of the creation of a group assignment, see "[Basics of setting up {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom)." + +### Prerequisites + +{% data reusables.classroom.assignments-classroom-prerequisite %} + +### Creating an assignment + +{% data reusables.classroom.assignments-guide-create-the-assignment %} + +### Setting up the basics for an assignment + +Name your assignment, decide whether to assign a deadline, define teams, and choose the visibility of assignment repositories. + +- [Naming an assignment](#naming-an-assignment) +- [Assigning a deadline for an assignment](#assigning-a-deadline-for-an-assignment) +- [Choosing an assignment type](#choosing-an-assignment-type) +- [Defining teams for an assignment](#defining-teams-for-an-assignment) +- [Choosing a visibility for assignment repositories](#choosing-a-visibility-for-assignment-repositories) + +#### Naming an assignment + +For a group assignment, {% data variables.product.prodname_classroom %} names repositories by the repository prefix and the name of the team. By default, the repository prefix is the assignment title. For example, if you name an assignment "assignment-1" and the team's name on {% data variables.product.product_name %} is "student-team", the name of the assignment repository for members of the team will be `assignment-1-student-team`. + +{% data reusables.classroom.assignments-type-a-title %} + +#### Assigning a deadline for an assignment + +{% data reusables.classroom.assignments-guide-assign-a-deadline %} + +#### Choosing an assignment type + +Under "Individual or group assignment", select the drop-down menu, then click **Group assignment**. You can't change the assignment type after you create the assignment. If you'd rather create a individual assignment, see "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)." + +#### Defining teams for an assignment + +If you've already created a group assignment for the classroom, you can reuse a set of teams for the new assignment. To create a new set with the teams that your students create for the assignment, type the name for the set. Optionally, type the maximum number of team members and total teams. + +{% tip %} + +**Tips**: + +- We recommend including details about the set of teams in the name for the set. For example, if you want to use the set of teams for one assignment, name the set after the assignment. If you want to reuse the set throughout a semester or course, name the set after the semester or course. + +- If you'd like to assign students to a specific team, give your students a name for the team and provide a list of members. + +{% endtip %} + + + +#### Choosing a visibility for assignment repositories + +{% data reusables.classroom.assignments-guide-choose-visibility %} + +{% data reusables.classroom.assignments-guide-click-continue-after-basics %} + +### Adding starter code and configuring a development environment + +{% data reusables.classroom.assignments-guide-intro-for-environment %} + +- [Choosing a template repository](#choosing-a-template-repository) +- [Choosing an online integrated development environment (IDE)](#choosing-an-online-integrated-development-environment-ide) + +#### Choosing a template repository + +By default, a new assignment will create an empty repository for each team that a student creates. {% data reusables.classroom.you-can-choose-a-template-repository %} For more information about template repositories, see "[Creating a template repository](/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)." + +{% data reusables.classroom.assignments-guide-choose-template-repository %} + +#### Choosing an online integrated development environment (IDE) + +{% data reusables.classroom.about-online-ides %} For more information, see "[Integrate {% data variables.product.prodname_classroom %} with an IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide)." + +{% data reusables.classroom.assignments-guide-choose-an-online-ide %} + +{% data reusables.classroom.assignments-guide-click-continue-after-starter-code-and-feedback %} + +### Providing feedback + +Optionally, you can automatically grade assignments and create a space for discussing each submission with the team. + +- [Testing assignments automatically](#testing-assignments-automatically) +- [Preventing changes to important files](#preventing-changes-to-important-files) +- [Creating a pull request for feedback](#creating-a-pull-request-for-feedback) + +#### Testing assignments automatically + +{% data reusables.classroom.assignments-guide-using-autograding %} + +#### Preventing changes to important files + +{% data reusables.classroom.assignments-guide-prevent-changes %} + +#### Creating a pull request for feedback + +{% data reusables.classroom.you-can-create-a-pull-request-for-feedback %} + +{% data reusables.classroom.assignments-guide-create-review-pull-request %} + +{% data reusables.classroom.assignments-guide-click-create-assignment-button %} + +### Inviting students to an assignment + +{% data reusables.classroom.assignments-guide-invite-students-to-assignment %} + +You can see the teams that are working on or have submitted an assignment in the **Teams** tab for the assignment. {% data reusables.classroom.assignments-to-prevent-submission %} + +
+ 
+
+
+### Next steps
+
+- After you create the assignment and your students form teams, team members can start work on the assignment using Git and {% data variables.product.product_name %}'s features. Students can clone the repository, push commits, manage branches, create and review pull requests, address merge conflicts, and discuss changes with issues. Both you and the team can review the commit history for the repository. For more information, see "[Getting started with {% data variables.product.prodname_dotcom %}](/github/getting-started-with-github)," "[Creating, cloning, and archiving repositories](/github/creating-cloning-and-archiving-repositories)," "[Using Git](/github/using-git)," and "[Collaborating with issues and pull requests](/github/collaborating-with-issues-and-pull-requests)," and the free course on [managing merge conflicts](https://lab.github.com/githubtraining/managing-merge-conflicts) from {% data variables.product.prodname_learning %}.
+
+- When a team finishes an assignment, you can review the files in the repository, or you can review the history and visualizations for the repository to better understand how the team collaborated. For more information, see "[Visualizing repository data with graphs](/github/visualizing-repository-data-with-graphs)."
+
+- You can provide feedback for an assignment by commenting on individual commits or lines in a pull request. For more information, see "[Commenting on a pull request](/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request)" and "[Opening an issue from code](/github/managing-your-work-on-github/opening-an-issue-from-code)." For more information about creating saved replies to provide feedback for common errors, see "[About saved replies](/github/writing-on-github/about-saved-replies)."
+
+### Further reading
+
+- "[Use {% data variables.product.prodname_dotcom %} in your classroom and research](/education/teach-and-learn-with-github-education/use-github-in-your-classroom-and-research)"
+- "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)"
+- [Using Existing Teams in Group Assignments?](https://education.github.community/t/using-existing-teams-in-group-assignments/6999) in the {% data variables.product.prodname_education %} Community
diff --git a/content/education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository.md b/content/education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository.md
new file mode 100644
index 000000000000..6e43553a3fc6
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository.md
@@ -0,0 +1,19 @@
+---
+title: Create an assignment from a template repository
+intro: You can create an assignment from a template repository to provide starter code, documentation, and other resources to your students.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/using-template-repos-for-assignments
+---
+
+You can use a template repository on {% data variables.product.product_name %} as starter code for an assignment on {% data variables.product.prodname_classroom %}. Your template repository can contain boilerplate code, documentation, and other resources for your students. For more information, see "[Creating a template repository](/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)."
+
+To use the template repository for your assignment, the template repository must be owned by your organization, or the visibility of the template repository must be public.
+
+{% data reusables.classroom.you-may-want-to-predefine-repository-settings %} For more information, see "[Configure default settings for assignment repositories](/education/manage-coursework-with-github-classroom/configure-default-settings-for-assignment-repositories)."
+
+### Further reading
+
+- "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)"
+- "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)"
diff --git a/content/education/manage-coursework-with-github-classroom/create-an-individual-assignment.md b/content/education/manage-coursework-with-github-classroom/create-an-individual-assignment.md
new file mode 100644
index 000000000000..f33d4a73debf
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/create-an-individual-assignment.md
@@ -0,0 +1,124 @@
+---
+title: Create an individual assignment
+intro: You can create an assignment for students in your course to complete individually.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/creating-an-individual-assignment
+ - /education/manage-coursework-with-github-classroom/create-an-individual-assignment
+---
+
+### About individual assignments
+
+{% data reusables.classroom.assignments-individual-definition %}
+
+{% data reusables.classroom.classroom-creates-individual-repositories %}
+
+{% data reusables.classroom.about-assignments %}
+
+For a video demonstration of the creation of an individual assignment, see "[Basics of setting up {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom)."
+
+### Prerequisites
+
+{% data reusables.classroom.assignments-classroom-prerequisite %}
+
+### Creating an assignment
+
+{% data reusables.classroom.assignments-guide-create-the-assignment %}
+
+### Setting up the basics for an assignment
+
+Name your assignment, decide whether to assign a deadline, and choose the visibility of assignment repositories.
+
+- [Naming an assignment](#naming-an-assignment)
+- [Assigning a deadline for an assignment](#assigning-a-deadline-for-an-assignment)
+- [Choosing an assignment type](#choosing-an-assignment-type)
+- [Choosing a visibility for assignment repositories](#choosing-a-visibility-for-assignment-repositories)
+
+#### Naming an assignment
+
+For an individual assignment, {% data variables.product.prodname_classroom %} names repositories by the repository prefix and the student's {% data variables.product.product_name %} username. By default, the repository prefix is the assignment title. For example, if you name an assignment "assignment-1" and the student's username on {% data variables.product.product_name %} is @octocat, the name of the assignment repository for @octocat will be `assignment-1-octocat`.
+
+{% data reusables.classroom.assignments-type-a-title %}
+
+#### Assigning a deadline for an assignment
+
+{% data reusables.classroom.assignments-guide-assign-a-deadline %}
+
+#### Choosing an assignment type
+
+Under "Individual or group assignment", select the drop-down menu, and click **Individual assignment**. You can't change the assignment type after you create the assignment. If you'd rather create a group assignment, see "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)."
+
+#### Choosing a visibility for assignment repositories
+
+{% data reusables.classroom.assignments-guide-choose-visibility %}
+
+{% data reusables.classroom.assignments-guide-click-continue-after-basics %}
+
+### Adding starter code and configuring a development environment
+
+{% data reusables.classroom.assignments-guide-intro-for-environment %}
+
+- [Choosing a template repository](#choosing-a-template-repository)
+- [Choosing an online integrated development environment (IDE)](#choosing-an-online-integrated-development-environment-ide)
+
+#### Choosing a template repository
+
+By default, a new assignment will create an empty repository for each student on the roster for the classroom. {% data reusables.classroom.you-can-choose-a-template-repository %} For more information about template repositories, see "[Creating a template repository](/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)."
+
+{% data reusables.classroom.assignments-guide-choose-template-repository %}
+
+{% data reusables.classroom.assignments-guide-click-continue-after-starter-code-and-feedback %}
+
+#### Choosing an online integrated development environment (IDE)
+
+{% data reusables.classroom.about-online-ides %} For more information, see "[Integrate {% data variables.product.prodname_classroom %} with an IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide)."
+
+{% data reusables.classroom.assignments-guide-choose-an-online-ide %}
+
+### Providing feedback for an assignment
+
+Optionally, you can automatically grade assignments and create a space for discussing each submission with the student.
+
+- [Testing assignments automatically](#testing-assignments-automatically)
+- [Preventing changes to important files](#preventing-changes-to-important-files)
+- [Creating a pull request for feedback](#creating-a-pull-request-for-feedback)
+
+#### Testing assignments automatically
+
+{% data reusables.classroom.assignments-guide-using-autograding %}
+
+#### Preventing changes to important files
+
+{% data reusables.classroom.assignments-guide-prevent-changes %}
+
+#### Creating a pull request for feedback
+
+{% data reusables.classroom.you-can-create-a-pull-request-for-feedback %}
+
+{% data reusables.classroom.assignments-guide-create-review-pull-request %}
+
+{% data reusables.classroom.assignments-guide-click-create-assignment-button %}
+
+### Inviting students to an assignment
+
+{% data reusables.classroom.assignments-guide-invite-students-to-assignment %}
+
+You can see whether a student has joined the classroom and accepted or submitted an assignment in the **All students** tab for the assignment. {% data reusables.classroom.assignments-to-prevent-submission %}
+
+
+
+ 
+
+
+### Next steps
+
+- Once you create the assignment, students can start work on the assignment using Git and {% data variables.product.product_name %}'s features. Students can clone the repository, push commits, manage branches, create and review pull requests, address merge conflicts, and discuss changes with issues. Both you and student can review the commit history for the repository. For more information, see "[Getting started with {% data variables.product.prodname_dotcom %}](/github/getting-started-with-github)," "[Creating, cloning, and archiving repositories](/github/creating-cloning-and-archiving-repositories)," "[Using Git](/github/using-git)," and "[Collaborating with issues and pull requests](/github/collaborating-with-issues-and-pull-requests)."
+
+- When a student finishes an assignment, you can review the files in the repository, or you can review the history and visualizations for the repository to better understand the student's work. For more information, see "[Visualizing repository data with graphs](/github/visualizing-repository-data-with-graphs)."
+
+- You can provide feedback for an assignment by commenting on individual commits or lines in a pull request. For more information, see "[Commenting on a pull request](/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request)" and "[Opening an issue from code](/github/managing-your-work-on-github/opening-an-issue-from-code)." For more information about creating saved replies to provide feedback for common errors, see "[About saved replies](/github/writing-on-github/about-saved-replies)."
+
+### Further reading
+
+- "[Use {% data variables.product.prodname_dotcom %} in your classroom and research](/education/teach-and-learn-with-github-education/use-github-in-your-classroom-and-research)"
+- "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)"
diff --git a/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom.md
new file mode 100644
index 000000000000..35585611c6f7
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom.md
@@ -0,0 +1,9 @@
+---
+title: Get started with GitHub Classroom
+shortTitle: Get started
+intro: Learn how to configure and use {% data variables.product.prodname_classroom %} to administer your course.
+mapTopic: true
+versions:
+ free-pro-team: '*'
+---
+
diff --git a/content/education/manage-coursework-with-github-classroom/glossary.md b/content/education/manage-coursework-with-github-classroom/glossary.md
new file mode 100644
index 000000000000..0fa62c1100c5
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/glossary.md
@@ -0,0 +1,52 @@
+---
+title: Glossary
+intro: You can review explanations of terminology for {% data variables.product.prodname_classroom %}.
+versions:
+ free-pro-team: '*'
+---
+
+### assignment
+
+An assignment is coursework in {% data variables.product.prodname_classroom %}. A teacher can assign an assignment to an individual student or a group of students. Teachers can import starter code for the assignment, assign students, and create a deadline for each assignment. For more information, see the definitions for "[individual assignment](#individual-assignment)" and "[group assignment](#group-assignment)."
+
+---
+
+### classroom
+
+A classroom is the basic unit of {% data variables.product.prodname_classroom %}. Teachers can use a classroom to organize and manage students, teaching assistants, and assignments for a single course. A classroom belongs to an organization on {% data variables.product.prodname_dotcom_the_website %}. To administer a classroom, you must be an organization owner for the organization on {% data variables.product.prodname_dotcom %}. For more information, see "[Manage classrooms](/education/manage-coursework-with-github-classroom/manage-classrooms)."
+
+---
+
+### {% data variables.product.prodname_classroom %}
+
+{% data variables.product.prodname_classroom %} is a web application for educators that provides course administration tools integrated with {% data variables.product.prodname_dotcom %}. For more information, see the [{% data variables.product.prodname_classroom %}](https://classroom.github.com/) website.
+
+---
+
+### group assignment
+
+{% data reusables.classroom.assignments-group-definition %} For more information, see "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)."
+
+---
+
+### identifier
+
+An identifier in {% data variables.product.prodname_classroom %} is a unique ID for a student participating in a course. For example, an identifier can be a student name, alphanumeric ID, or email address.
+
+---
+
+### individual assignment
+
+{% data reusables.classroom.assignments-individual-definition %} For more information, see "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)."
+
+---
+
+### roster
+
+A roster allows a teacher to manage students and assignment submissions in a classroom on {% data variables.product.prodname_classroom %}. Teachers can create a roster by entering a list of student identifiers, or by connecting {% data variables.product.prodname_classroom %} to a learning management system (LMS). For more information about identifiers, see the definition of "[identifier](#identifier)." For more information about connecting {% data variables.product.prodname_classroom %} to an LMS, see "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)."
+
+---
+
+### Further reading
+
+- "[{% data variables.product.prodname_dotcom %} glossary](/github/getting-started-with-github/github-glossary)"
diff --git a/content/education/manage-coursework-with-github-classroom/index.md b/content/education/manage-coursework-with-github-classroom/index.md
new file mode 100644
index 000000000000..f5a8689fa7d3
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/index.md
@@ -0,0 +1,32 @@
+---
+title: Manage coursework with GitHub Classroom
+shortTitle: '{% data variables.product.prodname_classroom %}'
+intro: With {% data variables.product.prodname_classroom %}, you can use {% data variables.product.product_name %} to administer or participate in a course about software development.
+versions:
+ free-pro-team: '*'
+---
+
+### Table of Contents
+
+{% topic_link_in_list /get-started-with-github-classroom %}
+ {% link_in_list /basics-of-setting-up-github-classroom %}
+ {% link_in_list /glossary %}
+
+{% topic_link_in_list /teach-with-github-classroom %}
+ {% link_in_list /manage-classrooms %}
+ {% link_in_list /create-an-individual-assignment %}
+ {% link_in_list /create-a-group-assignment %}
+ {% link_in_list /create-an-assignment-from-a-template-repository %}
+ {% link_in_list /leave-feedback-with-pull-requests %}
+ {% link_in_list /use-autograding %}
+ {% link_in_list /configure-default-settings-for-assignment-repositories %}
+ {% link_in_list /connect-a-learning-management-system-to-github-classroom %}
+
+{% topic_link_in_list /integrate-github-classroom-with-an-ide %}
+ {% link_in_list /integrate-github-classroom-with-an-online-ide %}
+ {% link_in_list /about-using-makecode-arcade-with-github-classroom %}
+ {% link_in_list /about-using-replit-with-github-classroom %}
+ {% link_in_list /run-student-code-in-an-online-ide %}
+
+{% topic_link_in_list /learn-with-github-classroom %}
+ {% link_in_list /view-autograding-results %}
diff --git a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide.md b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide.md
new file mode 100644
index 000000000000..bd4ea02cdc4f
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide.md
@@ -0,0 +1,8 @@
+---
+title: Integrate GitHub Classroom with an IDE
+shortTitle: Integrate with an IDE
+intro: You can help your students write, test, and debug code by preconfiguring a development environment for assignment repositories on {% data variables.product.prodname_classroom %}.
+mapTopic: true
+versions:
+ free-pro-team: '*'
+---
diff --git a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide.md b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide.md
new file mode 100644
index 000000000000..57bda74667a7
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide.md
@@ -0,0 +1,42 @@
+---
+title: Integrate GitHub Classroom with an online IDE
+shortTitle: Integrate with an online IDE
+intro: You can preconfigure a supported online integrated development environment (IDE) for assignments you create in {% data variables.product.prodname_classroom %}.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/online-ide-integrations
+---
+
+### About integration with an online IDE
+
+{% data reusables.classroom.about-online-ides %}
+
+After a student accepts an assignment with an online IDE, the README file in the student's assignment repository will contain a button to open the assignment in the IDE. The student can begin working immediately, and no additional configuration is necessary.
+
+
+
+### Supported online IDEs
+
+{% data variables.product.prodname_classroom %} supports the following online IDEs. You can learn more about the student experience for each IDE.
+
+| IDE | More information |
+| :- | :- |
+| Microsoft MakeCode Arcade | "[About using MakeCode Arcade with {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/about-using-makecode-arcade-with-github-classroom)" |
+| Repl.it | "[About using Repl.it with GitHub Classroom](/education/manage-coursework-with-github-classroom/about-using-replit-with-github-classroom)" |
+
+### Configuring an online IDE for an assignment
+
+You can choose the online IDE you'd like to use for an assignment when you create an assignment. To learn how to create a new assignment that uses an online IDE, see "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)" or "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)."
+
+### Authorizing the OAuth app for an online IDE
+
+The first time you configure an assignment with an online IDE, you must authorize the OAuth app for the online IDE for your organization.
+
+
+
+For all repositories, grant the app **read** access to metadata, administration, and code, and **write** access to administration and code. For more information, see "[Authorizing OAuth Apps](/github/authenticating-to-github/authorizing-oauth-apps)."
+
+### Further reading
+
+- "[About READMEs](/github/creating-cloning-and-archiving-repositories/about-readmes)"
diff --git a/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom.md
new file mode 100644
index 000000000000..0657de2a7290
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom.md
@@ -0,0 +1,7 @@
+---
+title: Learn with GitHub Classroom
+intro: You can participate in coursework in {% data variables.product.prodname_classroom %} and see results from your teacher.
+mapTopic: true
+versions:
+ free-pro-team: '*'
+---
diff --git a/content/education/manage-coursework-with-github-classroom/leave-feedback-with-pull-requests.md b/content/education/manage-coursework-with-github-classroom/leave-feedback-with-pull-requests.md
new file mode 100644
index 000000000000..abf11843b42f
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/leave-feedback-with-pull-requests.md
@@ -0,0 +1,33 @@
+---
+title: Leave feedback with pull requests
+intro: You can leave feedback for your students in a special pull request within the repository for each assignment.
+permissions: People with read permissions to a repository can leave feedback in a pull request for the repository.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/leaving-feedback-in-github
+---
+
+### About feedback pull requests for assignments
+
+{% data reusables.classroom.you-can-create-a-pull-request-for-feedback %}
+
+When you enable the pull request for feedback for an assignment, {% data variables.product.prodname_classroom %} will create a special pull request titled **Feedback** in the assignment repository for each student or team. The pull request automatically shows every commit that a student pushed to the assignment repository's default branch.
+
+### Prerequisites
+
+To create and access the feedback pull request, you must enable the feedback pull request when you create the assignment. {% data reusables.classroom.for-more-information-about-assignment-creation %}
+
+### Leaving feedback in a pull request for an assignment
+
+{% data reusables.classroom.sign-into-github-classroom %}
+1. In the list of classrooms, click the classroom with the assignment you want to review.
+ 
+{% data reusables.classroom.click-assignment-in-list %}
+1. To the right of the submission, click **Review**.
+ 
+1. Review the pull request. For more information, see "[Commenting on a pull request](/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request)."
+
+### Further reading
+
+- "[Integrate {% data variables.product.prodname_classroom %} with an IDE](http://localhost:4000/en/free-pro-team@latest/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide)"
diff --git a/content/education/manage-coursework-with-github-classroom/manage-classrooms.md b/content/education/manage-coursework-with-github-classroom/manage-classrooms.md
new file mode 100644
index 000000000000..b4b129c00624
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/manage-classrooms.md
@@ -0,0 +1,121 @@
+---
+title: Manage classrooms
+intro: You can create and manage a classroom for each course that you teach using {% data variables.product.prodname_classroom %}.
+permissions: Organization owners can manage a classroom for an organization.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/archive-a-classroom
+---
+
+### About classrooms
+
+{% data reusables.classroom.about-classrooms %}
+
+
+
+### About management of classrooms
+
+{% data variables.product.prodname_classroom %} uses organization accounts on {% data variables.product.product_name %} to manage permissions, administration, and security for each classroom that you create. Each organization can have multiple classrooms.
+
+After you create a classroom, {% data variables.product.prodname_classroom %} will prompt you to invite teaching assistants (TAs) and admins to the classroom. Each classroom can have one or more admins. Admins can be teachers, TAs, or any other course administrator who you'd like to have control over your classrooms on {% data variables.product.prodname_classroom %}.
+
+Invite TAs and admins to your classroom by inviting the user accounts on {% data variables.product.product_name %} to your organization as organization owners and sharing the URL for your classrom. Organization owners can administer any classroom for the organization. For more information, see "[Permission levels for an organization](/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization)" and "[Inviting users to join your organization](/github/setting-up-and-managing-organizations-and-teams/inviting-users-to-join-your-organization)."
+
+When you're done using a classroom, you can archive the classroom and refer to the classroom, roster, and assignments later, or you can delete the classroom if you no longer need the classroom.
+
+### About classroom rosters
+
+Each classroom has a roster. A roster is a list of identifiers for the students who participate in your course.
+
+When you first share the URL for an assignment with a student, the student must sign into {% data variables.product.product_name %} with a user account to link the user account to an identifier for the classroom. After the student links a user account, you can see the associated user account in the roster. You can also see when the student accepts or submits an assignment.
+
+
+
+### Prerequisites
+
+You must have an organization account on {% data variables.product.product_name %} to manage classrooms on {% data variables.product.prodname_classroom %}. For more information, see "[Types of {% data variables.product.company_short %} accounts](/github/getting-started-with-github/types-of-github-accounts#organization-accounts)" and "[Creating a new organization from scratch](/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch)."
+
+You must authorize the OAuth app for {% data variables.product.prodname_classroom %} for your organization to manage classrooms for your organization account. For more information, see "[Authorizing OAuth Apps](/github/authenticating-to-github/authorizing-oauth-apps)."
+
+### Creating a classroom
+
+{% data reusables.classroom.sign-into-github-classroom %}
+1. Click **New classroom**.
+ 
+{% data reusables.classroom.guide-create-new-classroom %}
+
+After you create a classroom, you can begin creating assignments for students. For more information, see "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)" or "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)."
+
+### Creating a roster for your classroom
+
+You can create a roster of the students who participate in your course.
+
+If your course already has a roster, you can update the students on the roster or delete the roster. For more information, see "[Adding a student to the roster for your classroom](#adding-students-to-the-roster-for-your-classroom)" or "[Deleting a roster for a classroom](#deleting-a-roster-for-a-classroom)."
+
+{% data reusables.classroom.sign-into-github-classroom %}
+{% data reusables.classroom.click-classroom-in-list %}
+{% data reusables.classroom.click-students %}
+1. To connect {% data variables.product.prodname_classroom %} to your LMS and import a roster, click {% octicon "mortar-board" aria-label="The mortar board icon" %} **Import from a learning management system** and follow the instructions. For more information, see "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)."
+ 
+1. To create a roster manually, type your student identifiers. Optionally, click **Upload a CSV or text file** to upload a file containing the identifiers.
+ 
+1. Click **Create roster**.
+ 
+
+### Adding students to the roster for your classroom
+
+Your classroom must have an existing roster to add students to the roster. For more information about creating a roster, see "[Creating a roster for your classrom](#creating-a-roster-for-your-classroom)."
+
+{% data reusables.classroom.sign-into-github-classroom %}
+{% data reusables.classroom.click-classroom-in-list %}
+{% data reusables.classroom.click-students %}
+1. To the right of "Classroom roster", click **Update students**.
+ 
+1. Follow the instructions to add students to the roster.
+ - To import students from an LMS, click **Sync from a learning management system**. For more information about importing a roster from an LMS, see "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)."
+ - To manually add students, under "Manually add students", click **Upload a CSV or text file** or type the identifiers for the students, then click **Add roster entries**.
+ 
+
+### Renaming a classroom
+
+{% data reusables.classroom.sign-into-github-classroom %}
+{% data reusables.classroom.click-classroom-in-list %}
+{% data reusables.classroom.click-settings %}
+1. Under "Classroom name", type a new name for the classroom.
+ 
+1. Click **Rename classroom**.
+ 
+
+### Archiving or unarchiving a classroom
+
+You can archive a classroom that you no longer use on {% data variables.product.prodname_classroom %}. When you archive a classroom, you can't create new assignments or edit existing assignments for the classroom. Students can't accept invitations to assignments in archived classrooms.
+
+{% data reusables.classroom.sign-into-github-classroom %}
+1. To the right of a classroom's name, select the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} drop-down menu, then click **Archive**.
+ 
+1. To unarchive a classroom, to the right of a classroom's name, select the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} drop-down menu, then click **Unarchive**.
+ 
+
+### Deleting a roster for a classroom
+
+{% data reusables.classroom.sign-into-github-classroom %}
+{% data reusables.classroom.click-classroom-in-list %}
+{% data reusables.classroom.click-students %}
+1. Under "Delete this roster", click **Delete roster**.
+ 
+1. Read the warnings, then click **Delete roster**.
+ 
+
+### Deleting a classroom
+
+{% data reusables.classroom.sign-into-github-classroom %}
+{% data reusables.classroom.click-classroom-in-list %}
+{% data reusables.classroom.click-settings %}
+1. To the right of "Delete this classroom", click **Delete classroom**.
+ 
+1. **Read the warnings**.
+1. To verify that you're deleting the correct classroom, type the name of the classroom you want to delete.
+ 
+1. Click **Delete classroom**.
+ 
diff --git a/content/education/manage-coursework-with-github-classroom/run-student-code-in-an-online-ide.md b/content/education/manage-coursework-with-github-classroom/run-student-code-in-an-online-ide.md
new file mode 100644
index 000000000000..d74a5bf6962f
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/run-student-code-in-an-online-ide.md
@@ -0,0 +1,22 @@
+---
+title: Run student code in an online IDE
+intro: You can run the code from a student assignment within the online integrated development environment (IDE) that you configured for the assignment.
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/running-student-code
+---
+
+### About student code and online IDEs
+
+If you configure an online integrated development environment (IDE) for an assignment, you can run the code within the online IDE. You don't need to clone the assignment repository to your computer.
+
+For more information about online IDEs, see "[Integrate {% data variables.product.prodname_classroom %} with an online IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide)."
+
+### Running student code in the online IDE
+
+{% data reusables.classroom.sign-into-github-classroom %}
+{% data reusables.classroom.click-classroom-in-list %}
+{% data reusables.classroom.click-assignment-in-list %}
+1. To the right of the submission, click **View IDE**.
+ 
diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom.md
new file mode 100644
index 000000000000..6e051e9d2d82
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom.md
@@ -0,0 +1,8 @@
+---
+title: Teach with GitHub Classroom
+intro: Learn how to set up your classroom and assignments.
+mapTopic: true
+versions:
+ free-pro-team: '*'
+---
+
diff --git a/content/education/manage-coursework-with-github-classroom/use-autograding.md b/content/education/manage-coursework-with-github-classroom/use-autograding.md
new file mode 100644
index 000000000000..5218e1a12c38
--- /dev/null
+++ b/content/education/manage-coursework-with-github-classroom/use-autograding.md
@@ -0,0 +1,93 @@
+---
+title: Use autograding
+intro: You can automatically provide feedback on code submissions from your students by configuring tests to run in the assignment repository.
+miniTocMaxHeadingLevel: 4
+versions:
+ free-pro-team: '*'
+redirect_from:
+ - /education/manage-coursework-with-github-classroom/adding-tests-for-auto-grading
+ - /education/manage-coursework-with-github-classroom/reviewing-auto-graded-work-teachers
+---
+
+### About autograding
+
+{% data reusables.classroom.about-autograding %}
+
+After a student accepts an assignment, on every push to the assignment repository, {% data variables.product.prodname_actions %} runs the commands for your autograding test in a Linux environment containing the student's newest code. {% data variables.product.prodname_classroom %} creates the necessary workflows for {% data variables.product.prodname_actions %}. You don't need experience with {% data variables.product.prodname_actions %} to use autograding.
+
+You can use a testing framework, run a custom command, write input/output tests, or combine different testing methods. The Linux environment for autograding contains many popular software tools. For more information, see the details for the latest version of Ubuntu in "[Specifications for {% data variables.product.company_short %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners#supported-software)."
+
+You can see an overview of which students are passing autograding tests by navigating to the assignment in {% data variables.product.prodname_classroom %}. A green checkmark means that all tests are passing for the student, and a red X means that some or all tests are failing for the student. If you award points for one or more tests, then a bubble shows the score for the tests out of the maximum possible score for the assignment.
+
+
+
+### Grading methods
+
+There are two grading methods: input/output tests and run command tests.
+
+#### Input/output test
+
+An input/output test optionally runs a setup command, then provides standard input to a test command. {% data variables.product.prodname_classroom %} evaluates the test command's output against an expected result.
+
+| Setting | Description |
+| :- | :- |
+| **Test name** | The name of the test, to identify the test in logs |
+| **Setup command** | _Optional_. A command to run before tests, such as compilation or installation |
+| **Run command** | The command to run the test and generate standard output for evaluation |
+| **Inputs** | Standard input for run command |
+| **Expected output** | The output that you want to see as standard output from the run command |
+| **Comparison** | The type of comparison between the run command's output and the expected output
+- **Included**: Passes when the expected output appears
anywhere in the standard output from the run command - **Exact**: Passes when the expected output is completely identical
to the standard output from the run command - **Regex**: Passes if the regular expression in expected
output matches against the standard output from the run command
user:USERNAME | [**user:octocat feedback**](https://github.com/search?q=user%3Aoctocat+feedback&type=Discussions) matches discussions with the word "feedback" from repositories owned by @octocat. |
+| org:ORGNAME | [**org:github**](https://github.com/search?q=org%3Agithub&type=Discussions&utf8=%E2%9C%93) matches discussions in repositories owned by the GitHub organization. |
+| repo:USERNAME/REPOSITORY | [**repo:nodejs/node created:<2021-01-01**](https://github.com/search?q=repo%3Anodejs%2Fnode+created%3A%3C2020-01-01&type=Discussions) matches discussions from @nodejs' Node.js runtime project that were created before January 2021. |
+
+### Filter by repository visibility
+
+You can filter by the visibility of the repository containing the discussions using the `is` qualifier. For more information, see "[About repository visibility](/github/creating-cloning-and-archiving-repositories/about-repository-visibility)."
+
+| Qualifier | Example
+| :- | :- |{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %}
+| `is:public` | [**is:public**](https://github.com/search?q=is%3Apublic&type=Discussions) matches discussions in public repositories.{% endif %}
+| `is:internal` | [**is:internal**](https://github.com/search?q=is%3Ainternal&type=Discussions) matches discussions in internal repositories.
+| `is:private` | [**is:private tiramisu**](https://github.com/search?q=is%3Aprivate+tiramisu&type=Discussions) matches discussions that contain the word "tiramisu" in private repositories you can access.
+
+### Search by author
+
+The `author` qualifier finds discussions created by a certain user.
+
+| Qualifier | Example |
+| :- | :- |
+| author:USERNAME | [**cool author:octocat**](https://github.com/search?q=cool+author%3Aoctocat&type=Discussions) matches discussions with the word "cool" that were created by @octocat. |
+| | [**bootstrap in:body author:octocat**](https://github.com/search?q=bootstrap+in%3Abody+author%3Aoctocat&type=Discussions) matches discussions created by @octocat that contain the word "bootstrap" in the body. |
+
+### Search by commenter
+
+The `commenter` qualifier finds discussions that contain a comment from a certain user.
+
+| Qualifier | Example |
+| :- | :- |
+| commenter:USERNAME | [**github commenter:becca org:github**](https://github.com/search?utf8=%E2%9C%93&q=github+commenter%3Abecca+org%3Agithub&type=Discussions) matches discussions in repositories owned by GitHub, that contain the word "github," and have a comment by @becca.
+
+### Search by a user that's involved in a discussion
+
+You can use the `involves` qualifier to find discussions that involve a certain user. The qualifier returns discussions that were either created by a certain user, mention the user, or contain comments by the user. The `involves` qualifier is a logical OR between the `author`, `mentions`, and `commenter` qualifiers for a single user.
+
+| Qualifier | Example |
+| :- | :- |
+| involves:USERNAME | **[involves:becca involves:octocat](https://github.com/search?q=involves%3Abecca+involves%3Aoctocat&type=Discussions)** matches discussions either @becca or @octocat are involved in.
+| | [**NOT beta in:body involves:becca**](https://github.com/search?q=NOT+beta+in%3Abody+involves%3Abecca&type=Discussions) matches discussions @becca is involved in that do not contain the word "beta" in the body.
+
+### Search by number of comments
+
+You can use the `comments` qualifier along with greater than, less than, and range qualifiers to search by the number of comments. For more information, see "[Understanding the search syntax](/github/searching-for-information-on-github/understanding-the-search-syntax)."
+
+| Qualifier | Example |
+| :- | :- |
+| comments:n | [**comments:>100**](https://github.com/search?q=comments%3A%3E100&type=Discussions) matches discussions with more than 100 comments.
+| | [**comments:500..1000**](https://github.com/search?q=comments%3A500..1000&type=Discussions) matches discussions with comments ranging from 500 to 1,000.
+
+### Search by number of interactions
+
+You can filter discussions by the number of interactions with the `interactions` qualifier along with greater than, less than, and range qualifiers. The interactions count is the number of reactions and comments on a discussion. For more information, see "[Understanding the search syntax](/github/searching-for-information-on-github/understanding-the-search-syntax)."
+
+| Qualifier | Example |
+| :- | :- |
+| interactions:n | [** interactions:>2000**](https://github.com/search?q=interactions%3A%3E2000) matches discussions with more than 2,000 interactions.
+| | [**interactions:500..1000**](https://github.com/search?q=interactions%3A500..1000) matches discussions with interactions ranging from 500 to 1,000.
+
+### Search by number of reactions
+
+You can filter discussions by the number of reactions using the `reactions` qualifier along with greater than, less than, and range qualifiers. For more information, see "[Understanding the search syntax](/github/searching-for-information-on-github/understanding-the-search-syntax)."
+
+| Qualifier | Example |
+| :- | :- |
+| reactions:n | [** reactions:>1000**](https://github.com/search?q=reactions%3A%3E500) matches discussions with more than 500 reactions.
+| | [**reactions:500..1000**](https://github.com/search?q=reactions%3A500..1000) matches discussions with reactions ranging from 500 to 1,000.
+
+### Search by when a discussion was created or last updated
+
+You can filter discussions based on times of creation, or when the discussion was last updated. For discussion creation, you can use the `created` qualifier; to find out when an discussion was last updated, use the `updated` qualifier.
+
+Both qualifiers take a date as a parameter. {% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %}
+
+{% data reusables.search.date_gt_lt %}
+
+| Qualifier | Example |
+| :- | :- |
+| created:YYYY-MM-DD | [**created:>2020-11-15**](https://github.com/search?q=created%3A%3E%3D2020-11-15&type=discussions) matches discussions that were created after November 15, 2020.
+| updated:YYYY-MM-DD | [**weird in:body updated:>=2020-02-01**](https://github.com/search?q=weird+in%3Abody+updated%3A%3E%3D2020-12-01&type=Discussions) matches discussions with the word "weird" in the body that were updated after December 2020.
+
+### Further reading
+
+- "[Sorting search results](/articles/sorting-search-results/)"
diff --git a/content/github/searching-for-information-on-github/searching-issues-and-pull-requests.md b/content/github/searching-for-information-on-github/searching-issues-and-pull-requests.md
index 7f94bdf32dcf..1ee2d6f95ed4 100644
--- a/content/github/searching-for-information-on-github/searching-issues-and-pull-requests.md
+++ b/content/github/searching-for-information-on-github/searching-issues-and-pull-requests.md
@@ -207,7 +207,7 @@ You can use the `comments` qualifier along with [greater than, less than, and ra
| Qualifier | Example
| ------------- | -------------
-| comments:n | [**state:closed comments:>100**](https://github.com/search?q=state%3Aclosed+comments%3A%3C100&type=Issues) matches closed issues with more than 100 comments.
+| comments:n | [**state:closed comments:>100**](https://github.com/search?q=state%3Aclosed+comments%3A%3E100&type=Issues) matches closed issues with more than 100 comments.
| | [**comments:500..1000**](https://github.com/search?q=comments%3A500..1000&type=Issues) matches issues with comments ranging from 500 to 1,000.
### Search by number of interactions
diff --git a/content/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-sponsors.md b/content/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-sponsors.md
index fec21f3ab71b..f5cb3931230f 100644
--- a/content/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-sponsors.md
+++ b/content/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-sponsors.md
@@ -9,6 +9,8 @@ versions:
{% data reusables.sponsors.sponsorship-details %}
+{% data reusables.sponsors.no-fees %}
+
{% data reusables.dotcom_billing.view-all-subscriptions %}
### Further reading
diff --git a/content/github/setting-up-and-managing-billing-and-payments-on-github/discounted-subscriptions-for-github-accounts.md b/content/github/setting-up-and-managing-billing-and-payments-on-github/discounted-subscriptions-for-github-accounts.md
index d8d5d87aa299..9a3b5f04c53f 100644
--- a/content/github/setting-up-and-managing-billing-and-payments-on-github/discounted-subscriptions-for-github-accounts.md
+++ b/content/github/setting-up-and-managing-billing-and-payments-on-github/discounted-subscriptions-for-github-accounts.md
@@ -18,11 +18,11 @@ versions:
### Discounts for personal accounts
-In addition to the unlimited public and private repositories for students and faculty with {% data variables.product.prodname_free_user %}, verified students can apply for the {% data variables.product.prodname_student_pack %} to receive additional benefits from {% data variables.product.prodname_dotcom %} partners. For more information, see "[Applying for a student developer pack](/articles/applying-for-a-student-developer-pack)."
+In addition to the unlimited public and private repositories for students and faculty with {% data variables.product.prodname_free_user %}, verified students can apply for the {% data variables.product.prodname_student_pack %} to receive additional benefits from {% data variables.product.prodname_dotcom %} partners. For more information, see "[Apply for a student developer pack](/education/teach-and-learn-with-github-education/apply-for-a-student-developer-pack)."
### Discounts for schools and universities
-Verified academic faculty can apply for {% data variables.product.prodname_team %} for teaching or academic research. For more information, see "[Using {% data variables.product.prodname_dotcom %} in your classroom and research](/articles/using-github-in-your-classroom-and-research)." You can also request educational materials goodies for your students. For more information, visit [{% data variables.product.prodname_education %}](https://education.github.com/).
+Verified academic faculty can apply for {% data variables.product.prodname_team %} for teaching or academic research. For more information, see "[Use {% data variables.product.prodname_dotcom %} in your classroom and research](/education/teach-and-learn-with-github-education/use-github-in-your-classroom-and-research)." You can also request educational materials goodies for your students. For more information, visit [{% data variables.product.prodname_education %}](https://education.github.com/).
### Discounts for nonprofits and libraries
diff --git a/content/github/setting-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship.md b/content/github/setting-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship.md
index 5ec6dafb61d3..4d9595814cb5 100644
--- a/content/github/setting-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship.md
+++ b/content/github/setting-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship.md
@@ -7,25 +7,24 @@ versions:
free-pro-team: '*'
---
-### Downgrading a sponsorship
+{% data reusables.sponsors.org-sponsors-release-phase %}
-When you downgrade a sponsorship, the change will become effective on your next billing date. {% data reusables.sponsors.no-refunds %}
+### About sponsorship downgrades
-{% data reusables.user_settings.access_settings %}
-{% data reusables.user_settings.billing %}
-{% data reusables.user_settings.subscriptions-tab %}
-{% data reusables.sponsors.change-tier %}
-4. On the right side of the page, next to your selected tier, click **Edit**.
- 
+When you downgrade or cancel a sponsorship, the change will become effective on your next billing date. {% data reusables.sponsors.no-refunds %}
+
+### Downgrading a sponsorship
+
+{% data reusables.sponsors.navigate-to-sponsored-account %}
+{% data reusables.sponsors.sponsorship-dashboard %}
{% data reusables.sponsors.select-a-tier %}
{% data reusables.sponsors.update-sponsorship %}
### Canceling a sponsorship
-When you cancel a sponsorship, the change will become effective on your next billing date. {% data reusables.sponsors.no-refunds %}
-
{% data reusables.user_settings.access_settings %}
{% data reusables.user_settings.billing %}
+{% data reusables.sponsors.billing-switcher %}
{% data reusables.user_settings.subscriptions-tab %}
3. Under "{% data variables.product.prodname_sponsors %}", to the right of the sponsored open source contributor, click {% octicon "triangle-down" aria-label="The down triangle octicon" %} next to your sponsored amount, then click **Cancel sponsorship**.
diff --git a/content/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship.md b/content/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship.md
index 7637a1e68b3a..cd65d50f26b1 100644
--- a/content/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship.md
+++ b/content/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship.md
@@ -7,13 +7,15 @@ versions:
free-pro-team: '*'
---
+{% data reusables.sponsors.org-sponsors-release-phase %}
+
+### About sponsorship upgrades
+
When you upgrade your sponsorship tier, the change will become effective immediately. {% data reusables.sponsors.prorated-sponsorship %}
-{% data reusables.user_settings.access_settings %}
-{% data reusables.user_settings.billing %}
-{% data reusables.user_settings.subscriptions-tab %}
-{% data reusables.sponsors.change-tier %}
-4. On the right side of the page, next to your selected tier, click **Edit**.
- 
+### Upgrading a sponsorship
+
+{% data reusables.sponsors.navigate-to-sponsored-account %}
+{% data reusables.sponsors.sponsorship-dashboard %}
{% data reusables.sponsors.select-a-tier %}
-{% data reusables.sponsors.update-sponsorship %}
+{% data reusables.sponsors.update-sponsorship %}
\ No newline at end of file
diff --git a/content/github/setting-up-and-managing-organizations-and-teams/index.md b/content/github/setting-up-and-managing-organizations-and-teams/index.md
index 21ca94abd51c..d1c440e8c576 100644
--- a/content/github/setting-up-and-managing-organizations-and-teams/index.md
+++ b/content/github/setting-up-and-managing-organizations-and-teams/index.md
@@ -84,13 +84,15 @@ versions:
{% link_in_list /disabling-or-limiting-github-actions-for-your-organization %}
{% link_in_list /configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization %}
{% link_in_list /setting-permissions-for-adding-outside-collaborators %}
- {% link_in_list /allowing-people-to-delete-issues-in-your-organization %}
+ {% link_in_list /allowing-people-to-delete-issues-in-your-organization %}{% if currentVersion == "free-pro-team@latest" %}
+ {% link_in_list /managing-discussion-creation-for-repositories-in-your-organization %}{% endif %}
{% link_in_list /setting-team-creation-permissions-in-your-organization %}
{% link_in_list /managing-scheduled-reminders-for-your-organization %}
{% link_in_list /managing-the-default-branch-name-for-repositories-in-your-organization %}
{% link_in_list /managing-default-labels-for-repositories-in-your-organization %}
{% link_in_list /changing-the-visibility-of-your-organizations-dependency-insights %}
{% link_in_list /managing-the-display-of-member-names-in-your-organization %}
+ {% link_in_list /managing-updates-from-accounts-your-organization-sponsors %}
{% link_in_list /disabling-publication-of-github-pages-sites-for-your-organization %}
{% link_in_list /deleting-an-organization-account %}
{% link_in_list /converting-an-organization-into-a-user %}
diff --git a/content/github/setting-up-and-managing-organizations-and-teams/managing-discussion-creation-for-repositories-in-your-organization.md b/content/github/setting-up-and-managing-organizations-and-teams/managing-discussion-creation-for-repositories-in-your-organization.md
new file mode 100644
index 000000000000..7f6719b4f8ba
--- /dev/null
+++ b/content/github/setting-up-and-managing-organizations-and-teams/managing-discussion-creation-for-repositories-in-your-organization.md
@@ -0,0 +1,27 @@
+---
+title: Managing discussion creation for repositories in your organization
+intro: You can choose the permission levels that members require to create discussions in repositories owned by your organization.
+permissions: Organization owners can manage discussion creation for repositories owned by the organization.
+versions:
+ free-pro-team: '*'
+---
+
+{% data reusables.discussions.beta %}
+
+### Allowing or disallowing users with read access to create discussions
+
+By default, organization members with read access can create discussions if a repository administrator or organization owner enables discussions for a repository owned by the organization.
+
+{% data reusables.profile.access_profile %}
+{% data reusables.profile.access_org %}
+{% data reusables.organizations.org_settings %}
+{% data reusables.organizations.member-privileges %}
+5. Under "Repository discussions", select or deselect **Allow users with read access to create discussions**.
+ 
+6. Click **Save**.
+ 
+
+### Further reading
+
+- "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)"
+- "[Managing discussions for your community](/discussions/managing-discussions-for-your-community)"
diff --git a/content/github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors.md b/content/github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors.md
new file mode 100644
index 000000000000..f60a66464441
--- /dev/null
+++ b/content/github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors.md
@@ -0,0 +1,25 @@
+---
+title: Managing updates from accounts your organization sponsors
+intro: You can manage the email address that receives updates from accounts your organization sponsors.
+versions:
+ free-pro-team: '*'
+permissions: Organization owners can manage updates from accounts the organization sponsors.
+---
+
+{% data reusables.sponsors.org-sponsors-release-phase %}
+
+The developers and organizations that your organization sponsors can send you updates about their work. You can manage the email address that receives these updates.
+
+You can also disable updates from accounts your organization sponsors. For more information, see "[Managing your sponsorship](/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship#managing-email-updates-for-your-sponsorship)."
+
+{% data reusables.profile.access_profile %}
+{% data reusables.profile.access_org %}
+{% data reusables.organizations.org_settings %}
+1. Under "Sponsors update email (Private)", type the email address you want to receive updates from accounts your organization sponsors.
+ 
+1. Click **Update profile**.
+ 
+
+### Further reading
+
+- "[Supporting the open source community with {% data variables.product.prodname_sponsors %}](/github/supporting-the-open-source-community-with-github-sponsors)"
\ No newline at end of file
diff --git a/content/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization.md b/content/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization.md
index 6b04032d743a..8add77b2f31e 100644
--- a/content/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization.md
+++ b/content/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization.md
@@ -55,6 +55,9 @@ Organization members can have *owner*{% if currentVersion == "free-pro-team@late
| Disable team discussions for an organization (see "[Disabling team discussions for your organization](/articles/disabling-team-discussions-for-your-organization)" for details) | **X** | | |{% if currentVersion == "free-pro-team@latest" %}
| Manage viewing of organization dependency insights (see "[Changing the visibility of your organization's dependency insights](/articles/changing-the-visibility-of-your-organizations-dependency-insights)" for details) | **X** | | |{% endif %}
| Set a team profile picture in **all teams** (see "[Setting your team's profile picture](/articles/setting-your-team-s-profile-picture)" for details) | **X** | | |
+| Sponsor accounts and manage the organization's sponsorships (see "[Sponsoring open-source contributors](/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-open-source-contributors)" for details) | **X** | **X** | |
+| Manage email updates from sponsored accounts (see "[Managing updates from accounts your organization's sponsors](/github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors)" for details) | **X** | | |
+| Attribute your sponsorships to another organization (see "[Attributing sponsorships to your organization](/github/supporting-the-open-source-community-with-github-sponsors/attributing-sponsorships-to-your-organization)" for details ) | **X** | | |
| Disable publication of {% data variables.product.prodname_pages %} sites from repositories in the organization (see "[Disabling publication of {% data variables.product.prodname_pages %} sites for your organization](/github/setting-up-and-managing-organizations-and-teams/disabling-publication-of-github-pages-sites-for-your-organization)" for details) | **X** | | |
| Manage security and analysis settings (see "[Managing security and analysis settings for your organization](/github/setting-up-and-managing-organizations-and-teams/managing-security-and-analysis-settings-for-your-organization)" for details) | **X** | | |
| Enable and enforce [SAML single sign-on](/articles/about-identity-and-access-management-with-saml-single-sign-on) | **X** | | |
diff --git a/content/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization.md b/content/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization.md
index 7170e14e6f7b..2d70d2590c22 100644
--- a/content/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization.md
+++ b/content/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization.md
@@ -114,7 +114,19 @@ In addition to managing organization-level settings, organization owners have ad
| [Delete or transfer repositories out of the organization](/articles/setting-permissions-for-deleting-or-transferring-repositories) | | | | | **X** |
| [Archive repositories](/articles/about-archiving-repositories) | | | | | **X** |{% if currentVersion == "free-pro-team@latest" %}
| Display a sponsor button (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)") | | | | | **X** |{% endif %}
-| Create autolink references to external resources, like JIRA or Zendesk (see "[Configuring autolinks to reference external resources](/articles/configuring-autolinks-to-reference-external-resources)") | | | | | **X** |
+| Create autolink references to external resources, like JIRA or Zendesk (see "[Configuring autolinks to reference external resources](/articles/configuring-autolinks-to-reference-external-resources)") | | | | | **X** |{% if currentVersion == "free-pro-team@latest" %}
+| Create [security advisories](/github/managing-security-vulnerabilities/about-github-security-advisories) | | | | | **X** | {% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
+| [View {% data variables.product.prodname_code_scanning %} alerts on pull requests](/github/finding-security-vulnerabilities-and-errors-in-your-code/triaging-code-scanning-alerts-in-pull-requests) | **X** | **X** | **X** | **X** | **X** |
+| [List, dismiss, and delete {% data variables.product.prodname_code_scanning %} alerts](/github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository) | | | **X** | **X** | **X** |{% endif %}{% if currentVersion == "free-pro-team@latest" %}
+| [Enable {% data variables.product.prodname_discussions %}](/github/administering-a-repository/enabling-or-disabling-github-discussions-for-a-repository) in a repository | | | | **X** | **X** |
+| [Create and edit categories](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository) for {% data variables.product.prodname_discussions %} | | | | **X** | **X** |
+| [Move a discussion to a different category](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository) | | | **X** | **X** | **X** |
+| [Transfer a discussion](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository) to a new repository| | | **X** | **X** | **X** |
+| [Manage pinned discussions](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository) | | | **X** | **X** | **X** |
+| [Convert issues to discussions in bulk](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository) | | | **X** | **X** | **X** |
+| [Lock and unlock discussions](/discussions/managing-discussions-for-your-community/moderating-discussions) | | **X** | **X** | **X** | **X** |
+| [Individually convert issues to discussions](/discussions/managing-discussions-for-your-community/moderating-discussions) | | **X** | **X** | **X** | **X** |
+| [Create new discussions and comment on existing discussions](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion) | **X** | **X** | **X** | **X** | **X** |{% endif %}
### Further reading
diff --git a/content/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization.md b/content/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization.md
index 1c3a69af505d..fcb5bd5ba785 100644
--- a/content/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization.md
+++ b/content/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization.md
@@ -81,7 +81,9 @@ Each category has a set of associated actions that you can filter on. For exampl
Use the `created` qualifier to filter events in the audit log based on when they occurred. {% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %}
-{% data reusables.search.date_gt_lt %} For example:
+{% data reusables.search.date_gt_lt %}
+
+For example:
* `created:2014-07-08` finds all events that occurred on July 8th, 2014.
* `created:>=2014-07-08` finds all events that occurred on or after July 8th, 2014.
@@ -105,25 +107,53 @@ Using the qualifier `country`, you can filter events in the audit log based on t
{% data reusables.audit_log.exported-log-keys-and-values %}
{% endif %}
-### Using the Audit log API
+### Using the audit log API
+
+You can interact with the audit log using the GraphQL API{% if currentVersion == "free-pro-team@latest" %} or the REST API{% endif %}.
+
+{% if currentVersion == "free-pro-team@latest" %}
+
+#### Using the GraphQL API
+
+{% endif %}
{% note %}
-**Note**: The Audit log API is available for organizations using {% data variables.product.prodname_enterprise %}. {% data reusables.gated-features.more-info-org-products %}
+**Note**: The audit log GraphQL API is available for organizations using {% data variables.product.prodname_enterprise %}. {% data reusables.gated-features.more-info-org-products %}
{% endnote %}
-To ensure a secure IP and maintain compliance for your organization, you can use the Audit log API to keep copies of your audit log data and monitor:
-* Access to your organization or repository settings.
-* Changes in permissions.
-* Added or removed users in an organization, repository, or team.
-* Users being promoted to admin.
-* Changes to permissions of a GitHub App.
+To ensure a secure IP and maintain compliance for your organization, you can use the audit log GraphQL API to keep copies of your audit log data and monitor:
+{% data reusables.audit_log.audit-log-api-info %}
+
+{% if currentVersion == "free-pro-team@latest" %}
+Note that you can't retrieve Git events using the GraphQL API.
+{% endif %}
The GraphQL response can include data for up to 90 to 120 days.
For example, you can make a GraphQL request to see all the new organization members added to your organization. For more information, see the "[GraphQL API Audit Log](/graphql/reference/interfaces#auditentry/)."
+{% if currentVersion == "free-pro-team@latest" %}
+
+#### Using the REST API
+
+{% note %}
+
+**Note**: The audit log REST API is available as a limited beta for users of {% data variables.product.prodname_ghe_cloud %} only. To join the beta, talk to your services or sales contact at {% data variables.product.company_short %}.
+
+{% endnote %}
+
+To ensure a secure IP and maintain compliance for your organization, you can use the audit log REST API to keep copies of your audit log data and monitor:
+{% data reusables.audit_log.audit-log-api-info %}
+* Git events, such as cloning, fetching, and pushing
+
+{% data reusables.audit_log.audit-log-git-events-retention %}
+
+For more information about the audit log REST API, see "[Organizations](/rest/reference/orgs#get-the-audit-log-for-an-organization)" in the REST API documentation.
+
+{% endif %}
+
### Audit log actions
An overview of some of the most common actions that are recorded as events in the audit log.
@@ -213,6 +243,28 @@ An overview of some of the most common actions that are recorded as events in th
| `update` | Triggered when [a reply to a team discussion post is edited](/articles/managing-disruptive-comments/#editing-a-comment).
| `destroy` | Triggered when [a reply to a team discussion post is deleted](/articles/managing-disruptive-comments/#deleting-a-comment).
+{% if currentVersion == "free-pro-team@latest" %}
+
+#### `git` category actions
+
+{% note %}
+
+**Note:** To access Git events in the audit log, you must use the audit log REST API. This functionality is available as a limited beta for users of {% data variables.product.prodname_ghe_cloud %} only. To join the beta, talk to your services or sales contact at {% data variables.product.company_short %}.
+
+For more information about the audit log REST API, see "[Organizations](/rest/reference/orgs#get-the-audit-log-for-an-organization)" in the REST API documentation.
+
+{% endnote %}
+
+{% data reusables.audit_log.audit-log-git-events-retention %}
+
+| Action | Description
+|---------|----------------------------
+| `clone` | Triggered when a repository is cloned.
+| `fetch` | Triggered when changes are fetched from a repository.
+| `push` | Triggered when changes are pushed to a repository.
+
+{% endif %}
+
#### `hook` category actions
| Action | Description
@@ -500,8 +552,20 @@ For more information, see "[Restricting publication of {% data variables.product
| Action | Description
|------------------|-------------------
-| repo_funding_link_button_toggle | Triggered when you enable or disable a sponsor button in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)")
-| repo_funding_links_file_action | Triggered when you change the FUNDING file in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)")
+| `repo_funding_link_button_toggle` | Triggered when you enable or disable a sponsor button in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)")
+| `repo_funding_links_file_action` | Triggered when you change the FUNDING file in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)")
+| `sponsor_sponsorship_cancel` | Triggered when you cancel a sponsorship (see "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)")
+| `sponsor_sponsorship_create` | Triggered when you sponsor an account (see "[Sponsoring an open source contributor](/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-an-open-source-contributor)")
+| `sponsor_sponsorship_preference_change` | Triggered when you change whether you receive email updates from a sponsored account (see "[Managing your sponsorship](/articles/managing-your-sponsorship)")
+| `sponsor_sponsorship_tier_change` | Triggered when you upgrade or downgrade your sponsorship (see "[Upgrading a sponsorship](/articles/upgrading-a-sponsorship)" and "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)")
+| `sponsored_developer_approve` | Triggered when your {% data variables.product.prodname_sponsors %} account is approved (see "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)")
+| `sponsored_developer_create` | Triggered when your {% data variables.product.prodname_sponsors %} account is created (see "[Setting up {% data variables.product.prodname_sponsors %} for your organizaion](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)")
+| `sponsored_developer_profile_update` | Triggered when you edit your sponsored organization profile (see "[Editing your profile details for {% data variables.product.prodname_sponsors %}](/github/supporting-the-open-source-community-with-github-sponsors/editing-your-profile-details-for-github-sponsors)")
+| `sponsored_developer_request_approval` | Triggered when you submit your application for {% data variables.product.prodname_sponsors %} for approval (see "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)")
+| `sponsored_developer_tier_description_update` | Triggered when you change the description for a sponsorship tier (see "[Changing your sponsorship tiers](/articles/changing-your-sponsorship-tiers)")
+| sponsored_developer_update_newsletter_send | Triggered when you send an email update to your sponsors (see "[Contacting your sponsors](/articles/contacting-your-sponsors)")
+| `waitlist_invite_sponsored_developer` | Triggered when you are invited to join {% data variables.product.prodname_sponsors %} from the waitlist (see "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)")
+| `waitlist_join` | Triggered when you join the waitlist to become a sponsored organization (see "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)")
{% endif %}
{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}
diff --git a/content/github/setting-up-and-managing-your-github-user-account/index.md b/content/github/setting-up-and-managing-your-github-user-account/index.md
index 6ce7743d9fb9..352849bd5716 100644
--- a/content/github/setting-up-and-managing-your-github-user-account/index.md
+++ b/content/github/setting-up-and-managing-your-github-user-account/index.md
@@ -14,6 +14,7 @@ versions:
{% topic_link_in_list /managing-user-account-settings %}
{% link_in_list /about-your-personal-dashboard %}
+ {% link_in_list /managing-your-theme-settings %}
{% link_in_list /changing-your-github-username %}
{% link_in_list /merging-multiple-user-accounts %}
{% link_in_list /converting-a-user-into-an-organization %}
diff --git a/content/github/setting-up-and-managing-your-github-user-account/managing-your-theme-settings.md b/content/github/setting-up-and-managing-your-github-user-account/managing-your-theme-settings.md
new file mode 100644
index 000000000000..37f6c586436a
--- /dev/null
+++ b/content/github/setting-up-and-managing-your-github-user-account/managing-your-theme-settings.md
@@ -0,0 +1,24 @@
+---
+title: Managing your theme settings
+intro: You can manage how {% data variables.product.product_name %} looks to you by setting a theme preference that either follows your system settings or always uses light mode or dark mode.
+versions:
+ free-pro-team: '*'
+---
+
+{% note %}
+
+**Note:** Theme settings is currently in beta and subject to change.
+
+{% endnote %}
+
+For choice and flexibility in how and when you use {% data variables.product.product_name %}, you can configure theme settings to change how {% data variables.product.product_name %} looks to you. You can choose from two themes, light and dark, or you can configure {% data variables.product.product_name %} to follow your system settings. Some developers use dark theme for personal preference, to reduce power consumption on certain devices, or to reduce eye strain in low-light conditions.
+
+{% data reusables.user_settings.access_settings %}
+1. In the user settings sidebar, click **Appearance**.
+ 
+1. Under "Theme", select a theme preference.
+ 
+
+### Further reading
+
+- "[Setting a theme for {% data variables.product.prodname_desktop %}](/desktop/installing-and-configuring-github-desktop/setting-a-theme-for-github-desktop)"
diff --git a/content/github/site-policy/github-additional-product-terms.md b/content/github/site-policy/github-additional-product-terms.md
index 25a38b2efc7e..e1ce46499d28 100644
--- a/content/github/site-policy/github-additional-product-terms.md
+++ b/content/github/site-policy/github-additional-product-terms.md
@@ -4,7 +4,7 @@ versions:
free-pro-team: '*'
---
-Version Effective Date: November 13, 2020
+Version Effective Date: December 7, 2020
When you create an Account, you're given access to lots of different features and products that are all a part of the Service. Because many of these features and products offer different functionality, they may require additional terms and conditions specific to that feature or product. Below, we've listed those features and products, along with the corresponding additional terms that apply to your use of them.
@@ -108,3 +108,13 @@ We need the legal right to submit your contributions to the GitHub Advisory Data
#### b. License to the GitHub Advisory Database
The GitHub Advisory Database is licensed under the [Creative Commons Attribution 4.0 license](https://creativecommons.org/licenses/by/4.0/). The attribution term may be fulfilled by linking to the GitHub Advisory Database at Can read package metadata. | -| Write | Can upload and download this package.
Can read and write package metadata. | -| Admin | Can upload, download, delete, and manage this package.
Can read and write package metadata.
Can grant package permissions. - -For more information, see "[Configuring access control and visibility for container images](/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images)." - -### About billing for {% data variables.product.prodname_github_container_registry %} - -{% data reusables.package_registry.billing-for-container-registry %} - -### Contacting support - -If you have feedback or feature requests for {% data variables.product.prodname_github_container_registry %}, use the [feedback form](https://support.github.com/contact/feedback?contact%5Bcategory%5D=packages). - -Contact {% data variables.contact.github_support %} about {% data variables.product.prodname_github_container_registry %} using [our contact form](https://support.github.com/contact?form%5Bsubject%5D=Re:%20GitHub%20Packages) if: - -* You experience anything that contradicts the documentation. -* You encounter vague or unclear errors. -* Your published package contains sensitive data, such as GDPR violations, API Keys, or personally-identifying information. diff --git a/content/packages/getting-started-with-github-container-registry/index.md b/content/packages/getting-started-with-github-container-registry/index.md deleted file mode 100644 index f07fd0941c04..000000000000 --- a/content/packages/getting-started-with-github-container-registry/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Getting started with GitHub Container Registry -intro: 'Learn about {% data variables.product.prodname_container_registry %} concepts and how to migrate your Docker images from {% data variables.product.prodname_registry %}.' -versions: - free-pro-team: '*' ---- - -{% data reusables.package_registry.container-registry-beta %} - -{% link_in_list /about-github-container-registry %} -{% link_in_list /enabling-improved-container-support %} -{% link_in_list /core-concepts-for-github-container-registry %} -{% link_in_list /migrating-to-github-container-registry-for-docker-images %} - -For more information about configuring, deleting, pushing, or pulling container images, see "[Managing container images with {% data variables.product.prodname_github_container_registry %}](/packages/managing-container-images-with-github-container-registry)." diff --git a/content/packages/guides/about-github-container-registry.md b/content/packages/guides/about-github-container-registry.md new file mode 100644 index 000000000000..7a6984309cf5 --- /dev/null +++ b/content/packages/guides/about-github-container-registry.md @@ -0,0 +1,95 @@ +--- +title: About GitHub Container Registry +intro: 'You can use {% data variables.product.prodname_github_container_registry %} to seamlessly host and manage Docker container images in your organization or personal user account on {% data variables.product.prodname_dotcom %}. {% data variables.product.prodname_github_container_registry %} allows you to configure who can manage and access packages using fine-grained permissions.' +product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/getting-started-with-github-container-registry/about-github-container-registry + - /packages/managing-container-images-with-github-container-registry +versions: + free-pro-team: '*' +--- + +{% note %} + +**Note:** {% data variables.product.prodname_github_container_registry %} is currently in public beta and subject to change. During the beta, storage and bandwidth are free. To use {% data variables.product.prodname_github_container_registry %}, you must enable the feature for your account. For more information, see "[Enabling improved container support](/packages/guides/enabling-improved-container-support)." + +{% endnote %} + +### About {% data variables.product.prodname_github_container_registry %} + +{% data reusables.package_registry.container-registry-feature-highlights %} + +To share context about your package's use, you can link a repository to your container image on {% data variables.product.prodname_dotcom %}. For more information, see "[Connecting a repository to a container image](/packages/guides/connecting-a-repository-to-a-container-image)." + +{% data variables.product.prodname_github_container_registry %} has different hosting locations, permission, and visibility than other package registries. + +| | Package registries | {% data variables.product.prodname_github_container_registry %} | +|----|----|----| +| Hosting locations | You can host multiple packages in one repository. | You can host multiple container images in one organization or user account. | +| Permissions | Each package inherits the permissions of the repository where the package is hosted.
For example, anyone with read permissions for a repository can install a package as a dependency in a project, and anyone with write permissions can publish a new package version. | For each container image, you can choose the access level that others have. The permissions for container image access are separate from your organization and repository permissions. +Visibility | {% data reusables.package_registry.public-or-private-packages %} | You can set the visibility of each of your container images. A private container image is only visible to people and teams who are given access within your organization. A public container image is visible to anyone. | +Anonymous access | N/A | You can access public container images anonymously. + +For more information, see "[About scopes and permissions for {% data variables.product.prodname_github_container_registry %}](#about-scopes-and-permissions-for-github-container-registry)." + +### Supported formats + +The {% data variables.product.prodname_container_registry %} currently supports the following container image formats: + +* [Docker Image Manifest V2, Schema 2](https://docs.docker.com/registry/spec/manifest-v2-2/) +* [Open Container Initiative (OCI) Specifications](https://github.com/opencontainers/image-spec) + +The {% data variables.product.prodname_github_container_registry %} hosts containers at `ghcr.io/OWNER/IMAGE-NAME`. + +| Package client | Language | Package format | Description | +| --- | --- | --- | --- | +| Docker CLI | N/A | `Dockerfile` | Docker container support. | + + +#### Manifest Lists/Image Indexes + +{% data variables.product.prodname_github_container_registry %} also supports [Docker Manifest List](https://docs.docker.com/registry/spec/manifest-v2-2/#manifest-list)/[OCI Image Index](https://github.com/opencontainers/image-spec/blob/79b036d80240ae530a8de15e1d21c7ab9292c693/image-index.md) formats which are defined in the Docker V2, Schema 2 and OCI image specifications. + +### Visibility and access permissions for container images + +If you have admin permissions to a container image, you can set the container image to private or public. Public images allow anonymous access and can be pulled without authentication or signing in via the CLI. + +As an admin, you can also grant access permissions for a container image that are separate from the permissions you've set at the organization and repository levels. + +For container images published and owned by a user account, you can give any person an access role. For container images published and owned by an organization, you can give any person or team in the organization an access role. + +| Permission role | Access description | +|-----|----| +| Read | Can download package.
Can read package metadata. | +| Write | Can upload and download this package.
Can read and write package metadata. | +| Admin | Can upload, download, delete, and manage this package.
Can read and write package metadata.
Can grant package permissions. + +For more information, see "[Configuring access control and visibility for container images](/packages/guides/configuring-access-control-and-visibility-for-container-images)." + +### About scopes and permissions for {% data variables.product.prodname_github_container_registry %} + +To use or manage a package hosted by a package registry, you must use a token with the appropriate scope, and your user account must have appropriate permissions for that repository. + +| Scope | Description | +| --- | --- | +|`read:packages`| Download and install container images from {% data variables.product.prodname_github_container_registry %} | +|`write:packages`| Upload and publish container images to {% data variables.product.prodname_github_container_registry %} | +| `delete:packages` | Delete specified versions of private or public container images from {% data variables.product.prodname_github_container_registry %}. For more information, see "[Deleting a container image](/packages/guides/deleting-a-container-image)." | + +To learn about available scopes and permissions for container images, see "[Configuring access control and visibility for container images](/packages/guides/configuring-access-control-and-visibility-for-container-images)." + +For more information, see "[Creating a personal access token](/github/authenticating-to-github/creating-a-personal-access-token/)" and "[Available scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/#available-scopes)." + +### About billing for {% data variables.product.prodname_github_container_registry %} + +{% data reusables.package_registry.billing-for-container-registry %} + +### Contacting support + +If you have feedback or feature requests for {% data variables.product.prodname_github_container_registry %}, use the [feedback form](https://support.github.com/contact/feedback?contact%5Bcategory%5D=packages). + +Contact {% data variables.contact.github_support %} about {% data variables.product.prodname_github_container_registry %} using [our contact form](https://support.github.com/contact?form%5Bsubject%5D=Re:%20GitHub%20Packages) if: + +* You experience anything that contradicts the documentation. +* You encounter vague or unclear errors. +* Your published package contains sensitive data, such as GDPR violations, API Keys, or personally-identifying information. diff --git a/content/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images.md b/content/packages/guides/configuring-access-control-and-visibility-for-container-images.md similarity index 97% rename from content/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images.md rename to content/packages/guides/configuring-access-control-and-visibility-for-container-images.md index 8779fdf8efde..bff3dfee0ca8 100644 --- a/content/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images.md +++ b/content/packages/guides/configuring-access-control-and-visibility-for-container-images.md @@ -2,6 +2,8 @@ title: Configuring access control and visibility for container images intro: 'Choose who has read, write, or admin access to your container image and the visibility of your container images on {% data variables.product.prodname_dotcom %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images versions: free-pro-team: '*' --- diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages.md b/content/packages/guides/configuring-apache-maven-for-use-with-github-packages.md similarity index 96% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages.md rename to content/packages/guides/configuring-apache-maven-for-use-with-github-packages.md index 0d8c2df1cca7..62ffeb833cf9 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-apache-maven-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-apache-maven-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-apache-maven-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-apache-maven-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' @@ -188,5 +189,5 @@ To install an Apache Maven package from {% data variables.product.prodname_regis ### Further reading -- "[Configuring Gradle for use with {% data variables.product.prodname_registry %}](/packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages)" -- "[Deleting a package](/packages/publishing-and-managing-packages/deleting-a-package/)" +- "[Configuring Gradle for use with {% data variables.product.prodname_registry %}](/packages/guides/configuring-gradle-for-use-with-github-packages)" +- "[Deleting a package](/packages/manage-packages/deleting-a-package/)" diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages.md b/content/packages/guides/configuring-docker-for-use-with-github-packages.md similarity index 98% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages.md rename to content/packages/guides/configuring-docker-for-use-with-github-packages.md index d31c4e2c4a77..ce7cedc3e8c9 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-docker-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-docker-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-docker-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-docker-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages.md b/content/packages/guides/configuring-dotnet-cli-for-use-with-github-packages.md similarity index 98% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages.md rename to content/packages/guides/configuring-dotnet-cli-for-use-with-github-packages.md index a5fa36cc7e53..1c1369de9ffe 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-dotnet-cli-for-use-with-github-packages.md @@ -7,6 +7,7 @@ redirect_from: - /github/managing-packages-with-github-package-registry/configuring-nuget-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-nuget-for-use-with-github-packages - /github/managing-packages-with-github-packages/configuring-dotnet-cli-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages.md b/content/packages/guides/configuring-gradle-for-use-with-github-packages.md similarity index 98% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages.md rename to content/packages/guides/configuring-gradle-for-use-with-github-packages.md index 73502d9a8662..d84b907b011a 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-gradle-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-gradle-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-gradle-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-gradle-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages.md b/content/packages/guides/configuring-npm-for-use-with-github-packages.md similarity index 99% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages.md rename to content/packages/guides/configuring-npm-for-use-with-github-packages.md index 3ecb00119f7e..f96a8d68c694 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-npm-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-npm-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-npm-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages.md b/content/packages/guides/configuring-rubygems-for-use-with-github-packages.md similarity index 98% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages.md rename to content/packages/guides/configuring-rubygems-for-use-with-github-packages.md index b0e21632a83e..98ab1d6cb999 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-rubygems-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-rubygems-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-rubygems-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-rubygems-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image.md b/content/packages/guides/connecting-a-repository-to-a-container-image.md similarity index 96% rename from content/packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image.md rename to content/packages/guides/connecting-a-repository-to-a-container-image.md index 36623b8ecf9d..051f92283acb 100644 --- a/content/packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image.md +++ b/content/packages/guides/connecting-a-repository-to-a-container-image.md @@ -2,6 +2,8 @@ title: Connecting a repository to a container image intro: 'You can link a repository with a container image locally and on {% data variables.product.prodname_dotcom %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image versions: free-pro-team: '*' --- diff --git a/content/packages/guides/container-guides-for-github-packages.md b/content/packages/guides/container-guides-for-github-packages.md new file mode 100644 index 000000000000..31b8f63889a5 --- /dev/null +++ b/content/packages/guides/container-guides-for-github-packages.md @@ -0,0 +1,10 @@ +--- +title: Container guides for GitHub Packages +shortTitle: Container guides for GitHub Packages +intro: 'You can publish and retrieve Docker images using {% data variables.product.prodname_registry %}.' +mapTopic: true +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + diff --git a/content/packages/managing-container-images-with-github-container-registry/deleting-a-container-image.md b/content/packages/guides/deleting-a-container-image.md similarity index 94% rename from content/packages/managing-container-images-with-github-container-registry/deleting-a-container-image.md rename to content/packages/guides/deleting-a-container-image.md index 1ca7bff3fbdf..11c6cabf8168 100644 --- a/content/packages/managing-container-images-with-github-container-registry/deleting-a-container-image.md +++ b/content/packages/guides/deleting-a-container-image.md @@ -2,6 +2,8 @@ title: Deleting a container image intro: 'You can delete a version of a private container image using GraphQL or on {% data variables.product.prodname_dotcom %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/managing-container-images-with-github-container-registry/deleting-a-container-image versions: free-pro-team: '*' --- diff --git a/content/packages/getting-started-with-github-container-registry/enabling-improved-container-support.md b/content/packages/guides/enabling-improved-container-support.md similarity index 96% rename from content/packages/getting-started-with-github-container-registry/enabling-improved-container-support.md rename to content/packages/guides/enabling-improved-container-support.md index dbfccede7f4e..6b2aad74f0d5 100644 --- a/content/packages/getting-started-with-github-container-registry/enabling-improved-container-support.md +++ b/content/packages/guides/enabling-improved-container-support.md @@ -2,6 +2,8 @@ title: Enabling improved container support intro: 'To use {% data variables.product.prodname_github_container_registry %}, you must enable it for your user or organization account.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/getting-started-with-github-container-registry/enabling-improved-container-support versions: free-pro-team: '*' --- diff --git a/content/packages/guides/index.md b/content/packages/guides/index.md new file mode 100644 index 000000000000..fee52527360d --- /dev/null +++ b/content/packages/guides/index.md @@ -0,0 +1,33 @@ +--- +title: Guides +shortTitle: Guides +intro: 'These guides help you configure {% data variables.product.prodname_actions %} or your package client to work with {% data variables.product.prodname_registry %}.' +redirect_from: + - /github/managing-packages-with-github-packages/using-github-packages-with-your-projects-ecosystem + - /packages/using-github-packages-with-your-projects-ecosystem +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + +{% data reusables.package_registry.packages-ghes-release-stage %} + +### Table of Contents + +{% topic_link_in_list /package-client-guides-for-github-packages %} + {% link_in_list /using-github-packages-with-github-actions %} + {% link_in_list /configuring-apache-maven-for-use-with-github-packages %} + {% link_in_list /configuring-gradle-for-use-with-github-packages %} + {% link_in_list /configuring-npm-for-use-with-github-packages %} + {% link_in_list /configuring-dotnet-cli-for-use-with-github-packages %} + {% link_in_list /configuring-rubygems-for-use-with-github-packages %} +{% topic_link_in_list /container-guides-for-github-packages %} + {% link_in_list /configuring-docker-for-use-with-github-packages %} + {% link_in_list /about-github-container-registry %} + {% link_in_list /migrating-to-github-container-registry-for-docker-images %} + {% link_in_list /enabling-improved-container-support %} + {% link_in_list /configuring-access-control-and-visibility-for-container-images %} + {% link_in_list /connecting-a-repository-to-a-container-image %} + {% link_in_list /pushing-and-pulling-docker-images %} + {% link_in_list /deleting-a-container-image %} + diff --git a/content/packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images.md b/content/packages/guides/migrating-to-github-container-registry-for-docker-images.md similarity index 98% rename from content/packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images.md rename to content/packages/guides/migrating-to-github-container-registry-for-docker-images.md index 8f647b482509..239f2d6ae2f5 100644 --- a/content/packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images.md +++ b/content/packages/guides/migrating-to-github-container-registry-for-docker-images.md @@ -2,6 +2,8 @@ title: Migrating to GitHub Container Registry for Docker images intro: 'If you''ve used the GitHub Packages Docker registry to store Docker images, you can migrate to the new {% data variables.product.prodname_container_registry %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images versions: free-pro-team: '*' --- diff --git a/content/packages/guides/package-client-guides-for-github-packages.md b/content/packages/guides/package-client-guides-for-github-packages.md new file mode 100644 index 000000000000..6f77e8b9bd3e --- /dev/null +++ b/content/packages/guides/package-client-guides-for-github-packages.md @@ -0,0 +1,10 @@ +--- +title: Package client guides for GitHub Packages +shortTitle: Package client guides for GitHub Packages +intro: 'You can publish and retrieve package client images using {% data variables.product.prodname_registry %}.' +mapTopic: true +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + diff --git a/content/packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images.md b/content/packages/guides/pushing-and-pulling-docker-images.md similarity index 97% rename from content/packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images.md rename to content/packages/guides/pushing-and-pulling-docker-images.md index 5dd0f067e25a..8e38906fbdc7 100644 --- a/content/packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images.md +++ b/content/packages/guides/pushing-and-pulling-docker-images.md @@ -2,6 +2,8 @@ title: Pushing and pulling Docker images intro: 'You can store and manage Docker images in {% data variables.product.prodname_github_container_registry %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images versions: free-pro-team: '*' --- diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions.md b/content/packages/guides/using-github-packages-with-github-actions.md similarity index 97% rename from content/packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions.md rename to content/packages/guides/using-github-packages-with-github-actions.md index 8875879a16f7..bb4ed48ec696 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions.md +++ b/content/packages/guides/using-github-packages-with-github-actions.md @@ -4,6 +4,7 @@ intro: 'You can configure a workflow in {% data variables.product.prodname_actio product: '{% data reusables.gated-features.packages %}' redirect_from: - /github/managing-packages-with-github-packages/using-github-packages-with-github-actions + - /packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/index.md b/content/packages/index.md index e00d89f22a59..da52606f5d38 100644 --- a/content/packages/index.md +++ b/content/packages/index.md @@ -2,31 +2,43 @@ title: GitHub Packages Documentation shortTitle: GitHub Packages intro: 'Learn to safely publish and consume packages, store your packages alongside your code, and share your packages privately with your team or publicly with the open source community. You can also automate your packages with {% data variables.product.prodname_actions %}.' +introLinks: + quickstart: /packages/quickstart + reference: /packages/manage-packages featuredLinks: - gettingStarted: - - /packages/publishing-and-managing-packages/about-github-packages - - /packages/getting-started-with-github-container-registry/about-github-container-registry - - /packages/getting-started-with-github-container-registry - - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images - - /packages/publishing-and-managing-packages/publishing-a-package - - /packages/publishing-and-managing-packages/installing-a-package + guides: + - /packages/learn-github-packages + - /packages/guides/using-github-packages-with-github-actions + - /packages/manage-packages/installing-a-package popular: - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages - - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images - - /packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions + - /packages/guides/configuring-npm-for-use-with-github-packages + - /packages/learn-github-packages/about-github-packages + - /packages/guides/configuring-apache-maven-for-use-with-github-packages + guideCards: + - /packages/guides/configuring-npm-for-use-with-github-packages + - /packages/guides/enabling-improved-container-support + - /packages/guides/configuring-rubygems-for-use-with-github-packages +changelog: + - title: Packages container support is an opt-in beta + date: '2020-11-17' + href: https://docs.github.com/packages/getting-started-with-github-container-registry/enabling-improved-container-support + - title: Organization admins access to containers + date: '2020-11-16' + href: https://github.blog/changelog/2020-11-16-packages-organization-admins-access-to-containers/ + - title: Packages now respects IP allow list settings + date: '2020-11-12' + href: https://github.blog/changelog/2020-11-12-packages-now-respects-ip-allow-list-settings/ redirect_from: - /github/managing-packages-with-github-packages - /categories/managing-packages-with-github-package-registry - /github/managing-packages-with-github-package-registry +layout: product-landing versions: free-pro-team: '*' enterprise-server: '>=2.22' --- -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% link_with_intro /getting-started-with-github-container-registry %} -{% link_with_intro /managing-container-images-with-github-container-registry %} -{% link_with_intro /publishing-and-managing-packages %} -{% link_with_intro /using-github-packages-with-your-projects-ecosystem %} + + + + diff --git a/content/packages/publishing-and-managing-packages/about-github-packages.md b/content/packages/learn-github-packages/about-github-packages.md similarity index 72% rename from content/packages/publishing-and-managing-packages/about-github-packages.md rename to content/packages/learn-github-packages/about-github-packages.md index 433a30c1cf38..1e2ef5b46373 100644 --- a/content/packages/publishing-and-managing-packages/about-github-packages.md +++ b/content/packages/learn-github-packages/about-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/about-github-package-registry - /github/managing-packages-with-github-package-registry/about-github-package-registry - /github/managing-packages-with-github-packages/about-github-packages + - /packages/publishing-and-managing-packages/about-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' @@ -22,7 +23,7 @@ You can integrate {% data variables.product.prodname_registry %} with {% data va {% data variables.product.prodname_registry %} offers different package registries for commonly used packages, such as for Node, RubyGems, Apache Maven, Gradle, and Nuget. {% if currentVersion == "free-pro-team@latest" %} -{% data variables.product.prodname_registry %} also offers a {% data variables.product.prodname_container_registry %} designed to support the unique needs of container images. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)." +{% data variables.product.prodname_registry %} also offers a {% data variables.product.prodname_container_registry %} designed to support the unique needs of container images. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/guides/about-github-container-registry)." {% data reusables.package_registry.container-registry-beta %} @@ -32,34 +33,16 @@ You can integrate {% data variables.product.prodname_registry %} with {% data va #### Viewing packages -You can review the package's README, some metadata like licensing, download statistics, version history, and more on {% data variables.product.product_name %}. For more information, see "[Viewing packages](/packages/publishing-and-managing-packages/viewing-packages)." +You can review the package's README, some metadata like licensing, download statistics, version history, and more on {% data variables.product.product_name %}. For more information, see "[Viewing packages](/packages/manage-packages/viewing-packages)." #### About package permissions and visibility -{% if currentVersion == "free-pro-team@latest" %} - -| | Package registries | {% data variables.product.prodname_github_container_registry %} | -|----|----|----| -| Hosting locations | You can host multiple packages in one repository. | You can host multiple container images in one organization or user account. | -| Permissions | Each package inherits the permissions of the repository where the package is hosted.
For example, anyone with read permissions for a repository can install a package as a dependency in a project, and anyone with write permissions can publish a new package version. | For each container image, you can choose the access level that others have. The permissions for container image access are separate from your organization and repository permissions. -Visibility | {% data reusables.package_registry.public-or-private-packages %} | You can set the visibility of each of your container images. A private container image is only visible to people and teams who are given access within your organization. A public container image is visible to anyone. | -Anonymous access | N/A | You can access public container images anonymously. - -{% else %} | | Package registries | |----|----| | Hosting locations | You can host multiple packages in one repository. | | Permissions | Each package inherits the permissions of the repository where the package is hosted.
For example, anyone with read permissions for a repository can install a package as a dependency in a project, and anyone with write permissions can publish a new package version. | | Visibility | {% data reusables.package_registry.public-or-private-packages %} | -{% endif %} - -{% if currentVersion == "free-pro-team@latest" %} - -For more information about permissions and visibility for {% data variables.product.prodname_github_container_registry %}, see "[Configuring access control and visibility for containers](/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images)." - -{% endif %} - {% if currentVersion == "free-pro-team@latest" %} ### About billing for {% data variables.product.prodname_registry %} @@ -71,19 +54,6 @@ For more information about permissions and visibility for {% data variables.prod ### Supported clients and formats {% data variables.product.prodname_registry %} uses the native package tooling commands you're already familiar with to publish and install package versions. - -{% if currentVersion == "free-pro-team@latest" %} -#### Support for {% data variables.product.prodname_github_container_registry %} - -The {% data variables.product.prodname_github_container_registry %} hosts containers at `ghcr.io/OWNER/IMAGE-NAME`. - -| Package client | Language | Package format | Description | -| --- | --- | --- | --- | -| Docker CLI | N/A | `Dockerfile` | Docker container support. | - -For more information about the container support offered by {% data variables.product.prodname_github_container_registry %}, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)." -{% endif %} - #### Support for package registries {% if currentVersion == "free-pro-team@latest" %} @@ -142,34 +112,22 @@ For more information about subdomain isolation, see "[Enabling subdomain isolati {% endif %} -For more information about configuring your package client for use with {% data variables.product.prodname_registry %}, see "[Using {% data variables.product.prodname_registry %} with your project's ecosystem](/packages/using-github-packages-with-your-projects-ecosystem)." +For more information about configuring your package client for use with {% data variables.product.prodname_registry %}, see "[Package client guides for {% data variables.product.prodname_registry %}](/packages/guides/package-client-guides-for-github-packages)." +{% if currentVersion == "free-pro-team@latest" %} +For more information about Docker and {% data variables.product.prodname_github_container_registry %}, see "[Container guides for {% data variables.product.prodname_registry %}](/packages/guides/container-guides-for-github-packages)." +{% endif %} ### Authenticating to {% data variables.product.prodname_registry %} {% data reusables.package_registry.authenticate-packages %} -{% if currentVersion == "free-pro-team@latest" %} -### About scopes and permissions for {% data variables.product.prodname_github_container_registry %} - -| Scope | Description | -| --- | --- | -|`read:packages`| Download and install container images from {% data variables.product.prodname_github_container_registry %} | -|`write:packages`| Upload and publish container images to {% data variables.product.prodname_github_container_registry %} | -| `delete:packages` | Delete specified versions of private or public container images from {% data variables.product.prodname_github_container_registry %}. For more information, see "[Deleting a container image](/packages/managing-container-images-with-github-container-registry/deleting-a-container-image)." | - -To learn about available scopes and permissions for container images, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)" or "[Configuring access control and visibility for container images](/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images)." - -For more information, see "[Creating a personal access token](/github/authenticating-to-github/creating-a-personal-access-token/)" and "[Available scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/#available-scopes)." - -{% endif %} - ### About scopes and permissions for package registries To use or manage a package hosted by a package registry, you must use a token with the appropriate scope, and your user account must have appropriate permissions for that repository. For example: - To download and install packages from a repository, your token must have the `read:packages` scope, and your user account must have read permissions for the repository. -- To delete a specified version of a private package on {% data variables.product.product_name %}, your token must have the `delete:packages` and `repo` scope. Public packages cannot be deleted. For more information, see "[Deleting a package](/packages/publishing-and-managing-packages/deleting-a-package)." +- To delete a specified version of a private package on {% data variables.product.product_name %}, your token must have the `delete:packages` and `repo` scope. Public packages cannot be deleted. For more information, see "[Deleting a package](/packages/manage-packages/deleting-a-package)." | Scope | Description | Repository permissions | | --- | --- | --- | @@ -187,7 +145,7 @@ For more information, see: ### Managing packages -You can delete a version of a private package on {% data variables.product.product_name %} or using the GraphQL API. When you use the GraphQL API to query and delete private packages, you must use the same token you use to authenticate to {% data variables.product.prodname_registry %}. For more information, see "[Deleting a package](/packages/publishing-and-managing-packages/deleting-a-package)" and "[Forming calls with GraphQL](/graphql/guides/forming-calls-with-graphql)." +You can delete a version of a private package on {% data variables.product.product_name %} or using the GraphQL API. When you use the GraphQL API to query and delete private packages, you must use the same token you use to authenticate to {% data variables.product.prodname_registry %}. For more information, see "[Deleting a package](/packages/manage-packages/deleting-a-package)" and "[Forming calls with GraphQL](/graphql/guides/forming-calls-with-graphql)." You can configure webhooks to subscribe to package-related events, such as when a package is published or updated. For more information, see the "[`package` webhook event](/webhooks/event-payloads/#package)." diff --git a/content/packages/getting-started-with-github-container-registry/core-concepts-for-github-container-registry.md b/content/packages/learn-github-packages/core-concepts-for-github-packages.md similarity index 77% rename from content/packages/getting-started-with-github-container-registry/core-concepts-for-github-container-registry.md rename to content/packages/learn-github-packages/core-concepts-for-github-packages.md index 0eb31c63278e..07b7774cd7fc 100644 --- a/content/packages/getting-started-with-github-container-registry/core-concepts-for-github-container-registry.md +++ b/content/packages/learn-github-packages/core-concepts-for-github-packages.md @@ -1,16 +1,15 @@ --- -title: Core concepts for GitHub Container Registry -intro: 'Below is a list of common {% data variables.product.prodname_github_container_registry %} terms we use across our sites and documentation.' +title: Core concepts for GitHub Packages +intro: 'Below is a list of common {% data variables.product.prodname_registry %} terms we use across our sites and documentation.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/getting-started-with-github-container-registry/core-concepts-for-github-container-registry versions: free-pro-team: '*' + enterprise-server: '>=2.22' --- -{% data reusables.package_registry.container-registry-beta %} - -### {% data variables.product.prodname_github_container_registry %} - -The {% data variables.product.prodname_github_container_registry %} is a registry for containers with support for Docker images. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)." +{% data reusables.package_registry.packages-ghes-release-stage %} ### Package diff --git a/content/packages/learn-github-packages/index.md b/content/packages/learn-github-packages/index.md new file mode 100644 index 000000000000..a21e10fe4cbc --- /dev/null +++ b/content/packages/learn-github-packages/index.md @@ -0,0 +1,16 @@ +--- +title: Learn GitHub Packages +shortTitle: Learn GitHub Packages +intro: 'You can find out more about GitHub Packages, including publishing new packages to {% data variables.product.prodname_registry %}.' +redirect_from: + - /packages/getting-started-with-github-container-registry +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + +{% data reusables.package_registry.packages-ghes-release-stage %} + +{% link_in_list /about-github-packages %} +{% link_in_list /core-concepts-for-github-packages %} +{% link_in_list /publishing-a-package %} diff --git a/content/packages/publishing-and-managing-packages/publishing-a-package.md b/content/packages/learn-github-packages/publishing-a-package.md similarity index 97% rename from content/packages/publishing-and-managing-packages/publishing-a-package.md rename to content/packages/learn-github-packages/publishing-a-package.md index e44f7a900084..9294af45b6b9 100644 --- a/content/packages/publishing-and-managing-packages/publishing-a-package.md +++ b/content/packages/learn-github-packages/publishing-a-package.md @@ -4,6 +4,7 @@ intro: 'You can publish a package to {% data variables.product.prodname_registry product: '{% data reusables.gated-features.packages %}' redirect_from: - /github/managing-packages-with-github-packages/publishing-a-package + - /packages/publishing-and-managing-packages/publishing-a-package permissions: Anyone with write permissions for a repository can publish a package to that repository. versions: free-pro-team: '*' diff --git a/content/packages/publishing-and-managing-packages/deleting-a-package.md b/content/packages/manage-packages/deleting-a-package.md similarity index 96% rename from content/packages/publishing-and-managing-packages/deleting-a-package.md rename to content/packages/manage-packages/deleting-a-package.md index 3ac14a5879bc..b820d5f65afb 100644 --- a/content/packages/publishing-and-managing-packages/deleting-a-package.md +++ b/content/packages/manage-packages/deleting-a-package.md @@ -4,6 +4,7 @@ intro: 'You can delete a version of a private package using GraphQL or on {% dat product: '{% data reusables.gated-features.packages %}' redirect_from: - /github/managing-packages-with-github-packages/deleting-a-package + - /packages/publishing-and-managing-packages/deleting-a-package versions: free-pro-team: '*' enterprise-server: '>=2.22' @@ -14,7 +15,7 @@ versions: {% if currentVersion == "free-pro-team@latest" %} ### About container image deletion -To delete a container image package on {% data variables.product.product_name %}, see "[Deleting a container image](/packages/managing-container-images-with-github-container-registry/deleting-a-container-image)." +To delete a container image package on {% data variables.product.product_name %}, see "[Deleting a container image](/packages/guides/deleting-a-container-image)." {% endif %} diff --git a/content/packages/publishing-and-managing-packages/index.md b/content/packages/manage-packages/index.md similarity index 75% rename from content/packages/publishing-and-managing-packages/index.md rename to content/packages/manage-packages/index.md index e69cc46f750f..7f313028a1b0 100644 --- a/content/packages/publishing-and-managing-packages/index.md +++ b/content/packages/manage-packages/index.md @@ -1,9 +1,11 @@ --- -title: Publishing and managing packages -shortTitle: Publishing and managing packages +title: Managing GitHub packages +shortTitle: Managing GitHub packages intro: 'You can publish new packages to {% data variables.product.prodname_registry %}, view and install existing packages, and, in special circumstances, delete existing packages.' redirect_from: - /github/managing-packages-with-github-packages/publishing-and-managing-packages + - /github/packages/publishing-and-managing-packages + - /packages/publishing-and-managing-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' @@ -11,8 +13,6 @@ versions: {% data reusables.package_registry.packages-ghes-release-stage %} -{% link_in_list /about-github-packages %} -{% link_in_list /publishing-a-package %} {% link_in_list /viewing-packages %} {% link_in_list /installing-a-package %} {% link_in_list /deleting-a-package %} diff --git a/content/packages/publishing-and-managing-packages/installing-a-package.md b/content/packages/manage-packages/installing-a-package.md similarity index 96% rename from content/packages/publishing-and-managing-packages/installing-a-package.md rename to content/packages/manage-packages/installing-a-package.md index cb2b1f16ad28..007e34408996 100644 --- a/content/packages/publishing-and-managing-packages/installing-a-package.md +++ b/content/packages/manage-packages/installing-a-package.md @@ -4,6 +4,7 @@ intro: 'You can install a package from {% data variables.product.prodname_regist product: '{% data reusables.gated-features.packages %}' redirect_from: - /github/managing-packages-with-github-packages/installing-a-package + - /packages/publishing-and-managing-packages/installing-a-package permissions: Anyone with read permissions for a repository can install a package from that repository. versions: free-pro-team: '*' diff --git a/content/packages/publishing-and-managing-packages/viewing-packages.md b/content/packages/manage-packages/viewing-packages.md similarity index 97% rename from content/packages/publishing-and-managing-packages/viewing-packages.md rename to content/packages/manage-packages/viewing-packages.md index 55ba29e41806..d61604627ea1 100644 --- a/content/packages/publishing-and-managing-packages/viewing-packages.md +++ b/content/packages/manage-packages/viewing-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/viewing-a-repositorys-packages - /github/managing-packages-with-github-packages/publishing-and-managing-packages/viewing-a-repositorys-packages - /github/managing-packages-with-github-packages/viewing-packages + - /packages/publishing-and-managing-packages/viewing-packages permissions: Anyone with read permissions to a repository can view the repository's packages. versions: free-pro-team: '*' diff --git a/content/packages/managing-container-images-with-github-container-registry/index.md b/content/packages/managing-container-images-with-github-container-registry/index.md deleted file mode 100644 index c556ba7b516c..000000000000 --- a/content/packages/managing-container-images-with-github-container-registry/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Managing container images with GitHub Container Registry -intro: 'Learn how to manage container images using a supported CLI or on {% data variables.product.prodname_dotcom %}.' -versions: - free-pro-team: '*' ---- - -{% link_in_list /configuring-access-control-and-visibility-for-container-images %} -{% link_in_list /connecting-a-repository-to-a-container-image %} -{% link_in_list /pushing-and-pulling-docker-images %} -{% link_in_list /deleting-a-container-image %} diff --git a/content/packages/quickstart.md b/content/packages/quickstart.md new file mode 100644 index 000000000000..cf353a4d1b54 --- /dev/null +++ b/content/packages/quickstart.md @@ -0,0 +1,109 @@ +--- +title: Quickstart for GitHub Packages +intro: 'Publish to {% data variables.product.prodname_registry %} in 5 minutes or less with {% data variables.product.prodname_actions %}.' +allowTitleToDifferFromFilename: true +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + +### Introduction + +You only need an existing {% data variables.product.prodname_dotcom %} repository to publish a package to {% data variables.product.prodname_registry %}. In this guide, you'll create a {% data variables.product.prodname_actions %} workflow to test your code and then publish it to {% data variables.product.prodname_registry %}. Feel free to create a new repository for this Quickstart. You can use it to test this and future {% data variables.product.prodname_actions %} workflows. + +### Publishing your package + +1. Create a new repository on {% data variables.product.prodname_dotcom %}, adding the `.gitignore` for Node. Create a private repository if you’d like to delete this package later, public packages cannot be deleted. For more information, see "[Creating a new repository](/github/creating-cloning-and-archiving-repositories/creating-a-new-repository)." +2. Clone the repository to your local machine. + {% raw %} + ```shell + $ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git + $ cd YOUR-REPOSITORY + ``` + {% endraw %} +3. Create an `index.js` file and add a basic alert to say "Hello world!" + {% raw %} + ```javascript{:copy} + alert("Hello, World!"); + ``` + {% endraw %} +4. Initialize an npm package. In the package initialization wizard, enter your package with the name: _`@YOUR-USERNAME/YOUR-REPOSITORY`_, and set the test script to `exit 0` if you do not have any tests. Commit your changes and push them to {% data variables.product.prodname_dotcom %}. + {% raw %} + ```shell + $ npm init + ... + package name: @YOUR-USERNAME/YOUR-REPOSITORY + ... + test command: exit 0 + ... + + $ npm install + $ git add index.js package.json package-lock.json + $ git commit -m "initialize npm package" + $ git push + ``` + {% endraw %} +5. From your repository on {% data variables.product.prodname_dotcom %}, create a new file in the `.github/workflows` directory named `release-package.yml`. For more information, see "[Creating new files](/github/managing-files-in-a-repository/creating-new-files)." +6. Copy the following YAML content into the `release-package.yml` file. + {% raw %} + ```yaml{:copy} + name: Node.js Package + + on: + release: + types: [created] + + jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v1 + with: + node-version: 12 + - run: npm ci + - run: npm test + + publish-gpr: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v1 + with: + node-version: 12 + registry-url: https://npm.pkg.github.com/ + - run: npm ci + - run: npm publish + env: + NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} + ``` + {% endraw %} +7. Scroll to the bottom of the page and select **Create a new branch for this commit and start a pull request**. Then, to create a pull request, click **Propose new file**. +8. **Merge** the pull request. +9. Navigate to the **Code** tab and create a new release to test the workflow. For more information, see "[Managing releases in a repository](/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release)." + +Creating a new release in your repository triggers the workflow to build and test your code. If the tests pass, then the package will be published to {% data variables.product.prodname_registry %}. + +### Viewing your published package + +Packages are published at the repository level. You can see all the packages in a repository and search for a specific package. + +{% data reusables.repositories.navigate-to-repo %} +{% data reusables.package_registry.packages-from-code-tab %} +{% data reusables.package_registry.navigate-to-packages %} + + +### Installing a published package + +Now that you've published the package, you'll want to use it as a dependency across your projects. For more information, see "[Configuring npm for use with {% data variables.product.prodname_registry %}](/packages/guides/configuring-npm-for-use-with-github-packages#installing-a-package)." + +### Next steps + +The basic workflow you just added runs any time a new release is created in your repository. But, this is only the beginning of what you can do with {% data variables.product.prodname_registry %}. You can publish your package to multiple registries with a single workflow, trigger the workflow to run on different events such as a merged pull request, manage containers, and more. + +Combining {% data variables.product.prodname_registry %} and {% data variables.product.prodname_actions %} can help you automate nearly every aspect of your application development processes. Ready to get started? Here are some helpful resources for taking your next steps with {% data variables.product.prodname_registry %} and {% data variables.product.prodname_actions %}: + +- "[Learn {% data variables.product.prodname_registry %}](/packages/learn-github-packages)" for an in-depth tutorial on GitHub Packages +- "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)" for an in-depth tutorial on GitHub Actions +- "[Guides](/packages/guides)" for specific uses cases and examples diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/index.md b/content/packages/using-github-packages-with-your-projects-ecosystem/index.md deleted file mode 100644 index 02c88cf6323e..000000000000 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Using GitHub Packages with your project's ecosystem -shortTitle: Using GitHub Packages with your project's ecosystem -intro: 'You can configure {% data variables.product.prodname_actions %} or your package client to work with {% data variables.product.prodname_registry %}.' -redirect_from: - - /github/managing-packages-with-github-packages/using-github-packages-with-your-projects-ecosystem -versions: - free-pro-team: '*' - enterprise-server: '>=2.22' ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% link_in_list /using-github-packages-with-github-actions %} -{% link_in_list /configuring-docker-for-use-with-github-packages %} -{% link_in_list /configuring-apache-maven-for-use-with-github-packages %} -{% link_in_list /configuring-gradle-for-use-with-github-packages %} -{% link_in_list /configuring-npm-for-use-with-github-packages %} -{% link_in_list /configuring-dotnet-cli-for-use-with-github-packages %} -{% link_in_list /configuring-rubygems-for-use-with-github-packages %} diff --git a/content/rest/overview/resources-in-the-rest-api.md b/content/rest/overview/resources-in-the-rest-api.md index 30cc142a97e2..0dce11161924 100644 --- a/content/rest/overview/resources-in-the-rest-api.md +++ b/content/rest/overview/resources-in-the-rest-api.md @@ -301,18 +301,22 @@ gem: ### Pagination Requests that return multiple items will be paginated to 30 items by -default. You can specify further pages with the `?page` parameter. For some -resources, you can also set a custom page size up to 100 with the `?per_page` parameter. -Note that for technical reasons not all endpoints respect the `?per_page` parameter, +default. You can specify further pages with the `page` parameter. For some +resources, you can also set a custom page size up to 100 with the `per_page` parameter. +Note that for technical reasons not all endpoints respect the `per_page` parameter, see [events](/rest/reference/activity#events) for example. ```shell $ curl '{% data variables.product.api_url_pre %}/user/repos?page=2&per_page=100' ``` -Note that page numbering is 1-based and that omitting the `?page` +Note that page numbering is 1-based and that omitting the `page` parameter will return the first page. +Some endpoints use cursor-based pagination. A cursor is a string that points to a location in the result set. +With cursor-based pagination, there is no fixed concept of "pages" in the result set, so you can't navigate to a specific page. +Instead, you can traverse the results by using the `before` or `after` parameters. + For more information on pagination, check out our guide on [Traversing with Pagination][pagination-guide]. #### Link header @@ -323,13 +327,17 @@ For more information on pagination, check out our guide on [Traversing with Pagi {% endnote %} -The [Link header](http://tools.ietf.org/html/rfc5988) includes pagination information: +The [Link header](http://tools.ietf.org/html/rfc5988) includes pagination information. For example: Link: <{% data variables.product.api_url_code %}/user/repos?page=3&per_page=100>; rel="next", <{% data variables.product.api_url_code %}/user/repos?page=50&per_page=100>; rel="last" _The example includes a line break for readability._ +Or, if the endpoint uses cursor-based pagination: + + Link: <{% data variables.product.api_url_code %}/orgs/ORG/audit-log?after=MTYwMTkxOTU5NjQxM3xZbGI4VE5EZ1dvZTlla09uWjhoZFpR&before=>; rel="next", + This `Link` response header contains one or more [Hypermedia](/rest#hypermedia) link relations, some of which may require expansion as [URI templates](http://tools.ietf.org/html/rfc6570). The possible `rel` values are: diff --git a/content/rest/reference/enterprise-admin.md b/content/rest/reference/enterprise-admin.md index e95dc2be2a94..a35266becc0a 100644 --- a/content/rest/reference/enterprise-admin.md +++ b/content/rest/reference/enterprise-admin.md @@ -60,6 +60,16 @@ You can also read the current version by calling the [meta endpoint](/rest/refer {% endif %} +{% if currentVersion == "free-pro-team@latest" %} + +## Audit log + +{% for operation in currentRestOperations %} + {% if operation.subcategory == 'audit-log' %}{% include rest_operation %}{% endif %} +{% endfor %} + +{% endif %} + {% if currentVersion == "free-pro-team@latest" %} ## Billing diff --git a/data/products.yml b/data/products.yml index 1ec0286139de..e49c18cf2d40 100644 --- a/data/products.yml +++ b/data/products.yml @@ -4,10 +4,12 @@ productsInOrder: - github - admin + - discussions - actions - packages - developers - rest - graphql - insights + - education - desktop diff --git a/data/reusables/accounts/create-account.md b/data/reusables/accounts/create-account.md new file mode 100644 index 000000000000..dc817b083dd3 --- /dev/null +++ b/data/reusables/accounts/create-account.md @@ -0,0 +1,2 @@ +1. Go to {% data variables.product.product_name %}'s [Pricing]({% data variables.product.pricing_url %}) page. +2. Read the information about the different products and subscriptions that {% data variables.product.product_name %} offers, then click the upgrade button under the subscription you'd like to choose. diff --git a/data/reusables/actions/actions-not-verified.md b/data/reusables/actions/actions-not-verified.md index 2ab85ce6c125..3107e5a79f18 100644 --- a/data/reusables/actions/actions-not-verified.md +++ b/data/reusables/actions/actions-not-verified.md @@ -1 +1 @@ -Anyone can publish an action in {% data variables.product.prodname_marketplace %}. {% data variables.product.prodname_dotcom %} verifies some partner organizations, but unlike verified apps, {% data variables.product.prodname_dotcom %} does not review or verify individual actions listed in {% data variables.product.prodname_marketplace %}. +Anyone can publish an action in {% data variables.product.prodname_marketplace %}. {% data variables.product.prodname_dotcom %} verifies some partner organizations and these are shown as verified creators. diff --git a/data/reusables/actions/visualization-beta.md b/data/reusables/actions/visualization-beta.md new file mode 100644 index 000000000000..ee3ad11ef4b9 --- /dev/null +++ b/data/reusables/actions/visualization-beta.md @@ -0,0 +1,7 @@ +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +{% note %} + +**Note:** The workflow visualization graph for {% data variables.product.prodname_actions %} is currently in beta and subject to change. + +{% endnote %} +{% endif %} diff --git a/data/reusables/audit_log/audit-log-api-info.md b/data/reusables/audit_log/audit-log-api-info.md new file mode 100644 index 000000000000..55728a169240 --- /dev/null +++ b/data/reusables/audit_log/audit-log-api-info.md @@ -0,0 +1,5 @@ +* Access to your organization or repository settings +* Changes in permissions +* Added or removed users in an organization, repository, or team +* Users being promoted to admin +* Changes to permissions of a {% data variables.product.prodname_github_app %} diff --git a/data/reusables/audit_log/audit-log-git-events-retention.md b/data/reusables/audit_log/audit-log-git-events-retention.md new file mode 100644 index 000000000000..3f1584bf91a2 --- /dev/null +++ b/data/reusables/audit_log/audit-log-git-events-retention.md @@ -0,0 +1 @@ +The audit log retains Git events for 7 days. This is shorter than other audit log events, which can be retained for 90 days. diff --git a/data/reusables/classroom/about-assignments.md b/data/reusables/classroom/about-assignments.md new file mode 100644 index 000000000000..65a35062290d --- /dev/null +++ b/data/reusables/classroom/about-assignments.md @@ -0,0 +1 @@ +Each assignment has a title and an optional deadline. You can choose the visibility of repositories that {% data variables.product.prodname_classroom %} creates and choose access permissions. You can also automatically grade assignments and create a dedicated space to discuss the assignment with the student. diff --git a/data/reusables/classroom/about-autograding.md b/data/reusables/classroom/about-autograding.md new file mode 100644 index 000000000000..04ed2b067cae --- /dev/null +++ b/data/reusables/classroom/about-autograding.md @@ -0,0 +1 @@ +You can use autograding to automatically check a student's work for an assignment on {% data variables.product.prodname_classroom %}. You configure tests for an assignment, and the tests run immediately every time a student pushes to an assignment repository on {% data variables.product.product_location %}. The student can view the test results, make changes, and push to see new results. diff --git a/data/reusables/classroom/about-classrooms.md b/data/reusables/classroom/about-classrooms.md new file mode 100644 index 000000000000..5d19bbb44a95 --- /dev/null +++ b/data/reusables/classroom/about-classrooms.md @@ -0,0 +1 @@ +A classroom in {% data variables.product.prodname_classroom %} is where teachers and students interact during a course. Teachers can create a student roster for the classroom, then create, assign, review, and grade assignments within the classroom. diff --git a/data/reusables/classroom/about-online-ides.md b/data/reusables/classroom/about-online-ides.md new file mode 100644 index 000000000000..43818e691f57 --- /dev/null +++ b/data/reusables/classroom/about-online-ides.md @@ -0,0 +1 @@ +You can optionally configure an assignment to use an online integrated development environment (IDE). Online IDEs allow your students to write code, run programs, and collaborate in a browser, without installing Git and a full development toolchain on the student's computer. If you choose an online IDE for an assignment, students can still check out and run code locally on a computer with the necessary software. diff --git a/data/reusables/classroom/assignments-classroom-prerequisite.md b/data/reusables/classroom/assignments-classroom-prerequisite.md new file mode 100644 index 000000000000..06284dad51ae --- /dev/null +++ b/data/reusables/classroom/assignments-classroom-prerequisite.md @@ -0,0 +1 @@ +You must create a classroom before you can create an assignment. For more information, see "[Manage classrooms](/education/manage-coursework-with-github-classroom/manage-classrooms)." diff --git a/data/reusables/classroom/assignments-click-pencil.md b/data/reusables/classroom/assignments-click-pencil.md new file mode 100644 index 000000000000..e96536dbc16f --- /dev/null +++ b/data/reusables/classroom/assignments-click-pencil.md @@ -0,0 +1,2 @@ +1. To the right of the assignment you want to edit, click {% octicon "pencil" aria-label="The pencil icon" %}. +  diff --git a/data/reusables/classroom/assignments-group-definition.md b/data/reusables/classroom/assignments-group-definition.md new file mode 100644 index 000000000000..3143cddc7052 --- /dev/null +++ b/data/reusables/classroom/assignments-group-definition.md @@ -0,0 +1 @@ +A group assignment is collaborative coursework for groups of students on {% data variables.product.prodname_classroom %}. diff --git a/data/reusables/classroom/assignments-guide-assign-a-deadline.md b/data/reusables/classroom/assignments-guide-assign-a-deadline.md new file mode 100644 index 000000000000..6e8e29cc1182 --- /dev/null +++ b/data/reusables/classroom/assignments-guide-assign-a-deadline.md @@ -0,0 +1,5 @@ +Optionally, you can assign a deadline to the assignment. Under "Deadline (optional)", click in the text field, then use the date picker to assign a deadline. + +
+ 
+
diff --git a/data/reusables/classroom/assignments-guide-choose-an-online-ide.md b/data/reusables/classroom/assignments-guide-choose-an-online-ide.md
new file mode 100644
index 000000000000..54858178a519
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-choose-an-online-ide.md
@@ -0,0 +1,5 @@
+To choose an online IDE for the assignment, select the **Select an online IDE** drop-down menu, then click the IDE you'd like your students to use.
+
+
+
+ 
+
diff --git a/data/reusables/classroom/assignments-guide-choose-template-repository.md b/data/reusables/classroom/assignments-guide-choose-template-repository.md
new file mode 100644
index 000000000000..15bcb66cb5e4
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-choose-template-repository.md
@@ -0,0 +1,5 @@
+Under "Add a template repository to give students starter code", select the **Select a repository** drop-down, then type a search query. In the list of results, click the template repository you'd like to use for starter code.
+
+
+
+ 
+
diff --git a/data/reusables/classroom/assignments-guide-choose-visibility.md b/data/reusables/classroom/assignments-guide-choose-visibility.md
new file mode 100644
index 000000000000..3f4f17e1b2a9
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-choose-visibility.md
@@ -0,0 +1,9 @@
+The repositories for an assignment can be public or private. If you use private repositories, only the student or team can see the feedback you provide.
+
+You can also decide whether to grant students admin permissions to the repository for an assignment. Grant admin permissions if the student should be able to perform administrative tasks for the assignment repository. For more information, see "[About repository visibility](/github/creating-cloning-and-archiving-repositories/about-repository-visibility)" and "[Repository permission levels for an organization](/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization)."
+
+Under "Repository visibility", select a visibility. Optionally, select **Grant students admin access to their repository**.
+
+
+
+ 
+
diff --git a/data/reusables/classroom/assignments-guide-click-continue-after-basics.md b/data/reusables/classroom/assignments-guide-click-continue-after-basics.md
new file mode 100644
index 000000000000..b82d19fe8e1c
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-click-continue-after-basics.md
@@ -0,0 +1,7 @@
+
++ +When you're done, click **Continue** to configure starter code and a development environment for the assignment. + +
+ 
+
diff --git a/data/reusables/classroom/assignments-guide-click-continue-after-starter-code-and-feedback.md b/data/reusables/classroom/assignments-guide-click-continue-after-starter-code-and-feedback.md
new file mode 100644
index 000000000000..4607b61065bf
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-click-continue-after-starter-code-and-feedback.md
@@ -0,0 +1,7 @@
+
++ +When you're done, click **Continue** to configure automatic grading and feedback for the project. + +
+
+
diff --git a/data/reusables/classroom/assignments-guide-click-create-assignment-button.md b/data/reusables/classroom/assignments-guide-click-create-assignment-button.md
new file mode 100644
index 000000000000..935d73f5dfdc
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-click-create-assignment-button.md
@@ -0,0 +1,5 @@
+To create the assignment, click **Create assignment**.
+
+
+
+ 
+
diff --git a/data/reusables/classroom/assignments-guide-create-review-pull-request.md b/data/reusables/classroom/assignments-guide-create-review-pull-request.md
new file mode 100644
index 000000000000..5cc14ee9ff3d
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-create-review-pull-request.md
@@ -0,0 +1,5 @@
+To create pull requests for the discussion of feedback, select **Enable feedback pull requests**.
+
+
+
+ 
+
diff --git a/data/reusables/classroom/assignments-guide-create-the-assignment.md b/data/reusables/classroom/assignments-guide-create-the-assignment.md
new file mode 100644
index 000000000000..051e169c576f
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-create-the-assignment.md
@@ -0,0 +1,5 @@
+To create an assignment, sign into {% data variables.product.prodname_classroom_with_url %} and navigate to a classroom. In the {% octicon "repo" aria-label="The repo icon" %} **Assignments** tab, click **New assignment**.
+
+
+
+ 
+
diff --git a/data/reusables/classroom/assignments-guide-intro-for-environment.md b/data/reusables/classroom/assignments-guide-intro-for-environment.md
new file mode 100644
index 000000000000..bda2c39723cb
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-intro-for-environment.md
@@ -0,0 +1 @@
+Optionally, decide whether to provide empty repositories or starter code, and preconfigure a development environment for your students.
diff --git a/data/reusables/classroom/assignments-guide-invite-students-to-assignment.md b/data/reusables/classroom/assignments-guide-invite-students-to-assignment.md
new file mode 100644
index 000000000000..6290d808ad0f
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-invite-students-to-assignment.md
@@ -0,0 +1,3 @@
+{% data reusables.classroom.classroom-enables-invitation-urls %}
+
+{% data reusables.classroom.invitation-url-warning %}
diff --git a/data/reusables/classroom/assignments-guide-prevent-changes.md b/data/reusables/classroom/assignments-guide-prevent-changes.md
new file mode 100644
index 000000000000..9ef39a18b9ed
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-prevent-changes.md
@@ -0,0 +1,7 @@
+You can prevent students from changing files that contain tests for autograding, or other important files in the assignment repository.
+
+Under "Protected file paths", type relative paths within the repository to protect.
+
+
+
+ 
+
\ No newline at end of file
diff --git a/data/reusables/classroom/assignments-guide-using-autograding.md b/data/reusables/classroom/assignments-guide-using-autograding.md
new file mode 100644
index 000000000000..5f50beec64bf
--- /dev/null
+++ b/data/reusables/classroom/assignments-guide-using-autograding.md
@@ -0,0 +1,23 @@
+{% data reusables.classroom.about-autograding %} For more information, see "[Use autograding](/education/manage-coursework-with-github-classroom/use-autograding)."
+
+{% data reusables.classroom.use-add-test-drop-down-to-click-grading-method %} For more information, see "[Grading methods](/education/manage-coursework-with-github-classroom/use-autograding#grading-methods)."
+
+
+
+ 
+
+
+
++ +Define the parameters of your test case, like the name, commands, inputs, outputs, timeout, and points. When you're done, click **Save test case**. + +
+ 
+
+
+
++ +You can add more tests with the **Add test** drop-down menu, and you can edit or delete existing tests with {% octicon "pencil" aria-label="The pencil icon" %} or {% octicon "trash" aria-label="The trash icon" %}. + +
+ 
+
\ No newline at end of file
diff --git a/data/reusables/classroom/assignments-individual-definition.md b/data/reusables/classroom/assignments-individual-definition.md
new file mode 100644
index 000000000000..33425ae2c3f0
--- /dev/null
+++ b/data/reusables/classroom/assignments-individual-definition.md
@@ -0,0 +1 @@
+An individual assignment is coursework for each student who participates in a course on {% data variables.product.prodname_classroom %}. The student is intended to complete an individual assignment without help from other students.
diff --git a/data/reusables/classroom/assignments-to-prevent-submission.md b/data/reusables/classroom/assignments-to-prevent-submission.md
new file mode 100644
index 000000000000..62bd9cc2da96
--- /dev/null
+++ b/data/reusables/classroom/assignments-to-prevent-submission.md
@@ -0,0 +1 @@
+To prevent acceptance or submission of an assignment by students, deselect **Enable assignment invitation URL**. To edit the assignment, click {% octicon "pencil" aria-label="The pencil icon" %} **Edit assignment**.
diff --git a/data/reusables/classroom/assignments-type-a-title.md b/data/reusables/classroom/assignments-type-a-title.md
new file mode 100644
index 000000000000..20d32397ac46
--- /dev/null
+++ b/data/reusables/classroom/assignments-type-a-title.md
@@ -0,0 +1,5 @@
+Type a title for the assignment. Optionally, click {% octicon "pencil" aria-label="The pencil icon" %} to edit the prefix.
+
+
+
+ 
+
diff --git a/data/reusables/classroom/classroom-creates-group-repositories.md b/data/reusables/classroom/classroom-creates-group-repositories.md
new file mode 100644
index 000000000000..10cdc5924a51
--- /dev/null
+++ b/data/reusables/classroom/classroom-creates-group-repositories.md
@@ -0,0 +1 @@
+For each group assignment, {% data variables.product.prodname_classroom %} automatically creates a single shared repository for the team to access. The repository can be empty, or you can create the repository from a template repository with starter code, documentation, tests, and other resources. The repository belongs to your organization account on {% data variables.product.product_name %}, and {% data variables.product.prodname_classroom %} grants access to teams that students create or join when accepting the assignment.
diff --git a/data/reusables/classroom/classroom-creates-individual-repositories.md b/data/reusables/classroom/classroom-creates-individual-repositories.md
new file mode 100644
index 000000000000..4108abf9ad14
--- /dev/null
+++ b/data/reusables/classroom/classroom-creates-individual-repositories.md
@@ -0,0 +1 @@
+When a student accepts an assignment, {% data variables.product.prodname_classroom %} automatically creates a new repository for the student. The repositories can be empty, or you can create the repositories from a template repository with starter code, documentation, tests, and other resources. Each assignment repository belongs to your organization account on {% data variables.product.product_name %}.
diff --git a/data/reusables/classroom/classroom-enables-invitation-urls.md b/data/reusables/classroom/classroom-enables-invitation-urls.md
new file mode 100644
index 000000000000..1b357c3a2d16
--- /dev/null
+++ b/data/reusables/classroom/classroom-enables-invitation-urls.md
@@ -0,0 +1 @@
+By default, {% data variables.product.prodname_classroom %} enables an invitation URL for each assignment you create. Students can accept and submit the assignment while the invitation URL is enabled. You can share the URL with your students on your LMS, course homepage, or wherever you post assignments. Students can also navigate to the assignment on {% data variables.product.prodname_classroom %} if the student has already accepted an assignment for the classroom.
diff --git a/data/reusables/classroom/click-assignment-in-list.md b/data/reusables/classroom/click-assignment-in-list.md
new file mode 100644
index 000000000000..b95427c1f326
--- /dev/null
+++ b/data/reusables/classroom/click-assignment-in-list.md
@@ -0,0 +1,2 @@
+1. In the list of assignments, click the assignment you want to view.
+ 
diff --git a/data/reusables/classroom/click-classroom-in-list.md b/data/reusables/classroom/click-classroom-in-list.md
new file mode 100644
index 000000000000..c76b53cf5780
--- /dev/null
+++ b/data/reusables/classroom/click-classroom-in-list.md
@@ -0,0 +1,2 @@
+1. In the list of classrooms, click the classroom you want to view.
+ 
diff --git a/data/reusables/classroom/click-settings.md b/data/reusables/classroom/click-settings.md
new file mode 100644
index 000000000000..022f6f04bb8d
--- /dev/null
+++ b/data/reusables/classroom/click-settings.md
@@ -0,0 +1,2 @@
+1. Under the classroom name, click {% octicon "gear" aria-label="The gear icon" %} **Settings**.
+ 
diff --git a/data/reusables/classroom/click-students.md b/data/reusables/classroom/click-students.md
new file mode 100644
index 000000000000..0bcda9e0c166
--- /dev/null
+++ b/data/reusables/classroom/click-students.md
@@ -0,0 +1,2 @@
+1. Under the classroom name, click {% octicon "people" aria-label="The people icon" %} **Students**.
+ 
diff --git a/data/reusables/classroom/for-more-information-about-assignment-creation.md b/data/reusables/classroom/for-more-information-about-assignment-creation.md
new file mode 100644
index 000000000000..8fd113d76353
--- /dev/null
+++ b/data/reusables/classroom/for-more-information-about-assignment-creation.md
@@ -0,0 +1 @@
+For more information, see "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)" or "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)."
diff --git a/data/reusables/classroom/guide-create-new-classroom.md b/data/reusables/classroom/guide-create-new-classroom.md
new file mode 100644
index 000000000000..1ce37f9c07ee
--- /dev/null
+++ b/data/reusables/classroom/guide-create-new-classroom.md
@@ -0,0 +1,6 @@
+1. In the list of organizations, click the organization you'd like to use for your classroom. Optionally, you can create a new organization. For more information, see "[Creating a new organization from scratch](/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch)."
+ 
+1. Type the name for your classroom.
+ 
+1. Click **Create classroom**.
+ 
diff --git a/data/reusables/classroom/invitation-url-warning.md b/data/reusables/classroom/invitation-url-warning.md
new file mode 100644
index 000000000000..f85e808ddc27
--- /dev/null
+++ b/data/reusables/classroom/invitation-url-warning.md
@@ -0,0 +1,5 @@
+{% warning %}
+
+**Warning**: Be careful where you share invitation URLs. Anyone with an invitation URL for an assignment can accept the invitation and associate a user account on {% data variables.product.product_name %} with an identifier in your roster.
+
+{% endwarning %}
diff --git a/data/reusables/classroom/readme-contains-button-for-online-ide.md b/data/reusables/classroom/readme-contains-button-for-online-ide.md
new file mode 100644
index 000000000000..fac85f79f197
--- /dev/null
+++ b/data/reusables/classroom/readme-contains-button-for-online-ide.md
@@ -0,0 +1 @@
+When a student accepts an assignment with an online IDE, the assignment repository will include a _README.md_ file with a special button at the top of the file. The button links the student directly to the workspace in the online IDE.
diff --git a/data/reusables/classroom/sign-into-github-classroom.md b/data/reusables/classroom/sign-into-github-classroom.md
new file mode 100644
index 000000000000..578bf7213e51
--- /dev/null
+++ b/data/reusables/classroom/sign-into-github-classroom.md
@@ -0,0 +1 @@
+1. Sign into {% data variables.product.prodname_classroom_with_url %}.
diff --git a/data/reusables/classroom/use-add-test-drop-down-to-click-grading-method.md b/data/reusables/classroom/use-add-test-drop-down-to-click-grading-method.md
new file mode 100644
index 000000000000..2486daf0a441
--- /dev/null
+++ b/data/reusables/classroom/use-add-test-drop-down-to-click-grading-method.md
@@ -0,0 +1 @@
+Under "Add autograding tests", select the **Add test** drop-down menu, then click the grading method you want to use.
diff --git a/data/reusables/classroom/you-can-choose-a-template-repository.md b/data/reusables/classroom/you-can-choose-a-template-repository.md
new file mode 100644
index 000000000000..40eb9d273be6
--- /dev/null
+++ b/data/reusables/classroom/you-can-choose-a-template-repository.md
@@ -0,0 +1 @@
+You can optionally choose a template repository as starter code for the assignment. The template repository must belong to your organization or be a public repository on {% data variables.product.product_name %}.
diff --git a/data/reusables/classroom/you-can-create-a-pull-request-for-feedback.md b/data/reusables/classroom/you-can-create-a-pull-request-for-feedback.md
new file mode 100644
index 000000000000..e9592fb8327c
--- /dev/null
+++ b/data/reusables/classroom/you-can-create-a-pull-request-for-feedback.md
@@ -0,0 +1 @@
+You can automatically create a pull request where you can provide feedback and answer a student's questions about an assignment. For more information about the review of changes in a pull request, see "[Reviewing changes in pull requests](/github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests)."
diff --git a/data/reusables/classroom/you-may-want-to-predefine-repository-settings.md b/data/reusables/classroom/you-may-want-to-predefine-repository-settings.md
new file mode 100644
index 000000000000..af5be0c09812
--- /dev/null
+++ b/data/reusables/classroom/you-may-want-to-predefine-repository-settings.md
@@ -0,0 +1 @@
+You may want to predefine the default settings for the assignment repositories that {% data variables.product.prodname_classroom %} creates from a template repository. For example, you may want to disable issues, define labels for pull requests, or protect a branch in some or all of the repositories.
diff --git a/data/reusables/discussions/about-categories-and-formats.md b/data/reusables/discussions/about-categories-and-formats.md
new file mode 100644
index 000000000000..a17ca2ca53be
--- /dev/null
+++ b/data/reusables/discussions/about-categories-and-formats.md
@@ -0,0 +1 @@
+All discussions must be created in a category, and repository administrators and maintainers define the categories for a repository. Categories can contain open-ended conversations, or conversations with a question/answer format.
diff --git a/data/reusables/discussions/about-discussions.md b/data/reusables/discussions/about-discussions.md
new file mode 100644
index 000000000000..c61b8b0f0ad6
--- /dev/null
+++ b/data/reusables/discussions/about-discussions.md
@@ -0,0 +1 @@
+Discussions are an open forum for conversation among maintainers and the community for a project on {% data variables.product.product_name %}.
diff --git a/data/reusables/discussions/beta.md b/data/reusables/discussions/beta.md
new file mode 100644
index 000000000000..8562a9025f3c
--- /dev/null
+++ b/data/reusables/discussions/beta.md
@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** {% data variables.product.prodname_discussions %} is currently in beta and subject to change.
+
+{% endnote %}
diff --git a/data/reusables/discussions/click-discussion-in-list.md b/data/reusables/discussions/click-discussion-in-list.md
new file mode 100644
index 000000000000..642082d84249
--- /dev/null
+++ b/data/reusables/discussions/click-discussion-in-list.md
@@ -0,0 +1,2 @@
+1. In the list of discussions, click the discussion you want to view.
+ 
diff --git a/data/reusables/discussions/discussions-tab.md b/data/reusables/discussions/discussions-tab.md
new file mode 100644
index 000000000000..777580a39a6f
--- /dev/null
+++ b/data/reusables/discussions/discussions-tab.md
@@ -0,0 +1,2 @@
+1. Under your repository name, click {% octicon "comment-discussion" aria-label="The discussion icon" %} **Discussions**.
+ 
diff --git a/data/reusables/discussions/edit-categories.md b/data/reusables/discussions/edit-categories.md
new file mode 100644
index 000000000000..37225be09f8d
--- /dev/null
+++ b/data/reusables/discussions/edit-categories.md
@@ -0,0 +1,2 @@
+1. To the right of "Categories", click {% octicon "pencil" aria-label="The pencil icon" %}.
+ 
diff --git a/data/reusables/discussions/edit-category-details.md b/data/reusables/discussions/edit-category-details.md
new file mode 100644
index 000000000000..8004b70314c3
--- /dev/null
+++ b/data/reusables/discussions/edit-category-details.md
@@ -0,0 +1 @@
+Edit the emoji, title, description, and discussion format for the category. For more information about discussion formats, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)."
diff --git a/data/reusables/discussions/enabling-or-disabling-github-discussions-for-your-repository.md b/data/reusables/discussions/enabling-or-disabling-github-discussions-for-your-repository.md
new file mode 100644
index 000000000000..343f6d8a22d7
--- /dev/null
+++ b/data/reusables/discussions/enabling-or-disabling-github-discussions-for-your-repository.md
@@ -0,0 +1,6 @@
+You can enable or disable discussions for a repository.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+1. Under "Features", select **Discussions**.
+ 
diff --git a/data/reusables/discussions/github-recognizes-members.md b/data/reusables/discussions/github-recognizes-members.md
new file mode 100644
index 000000000000..b6874b910d34
--- /dev/null
+++ b/data/reusables/discussions/github-recognizes-members.md
@@ -0,0 +1 @@
+{% data variables.product.prodname_dotcom %} will automatically recognize community members who contribute the most comments marked as answers to discussions with a question/answer format.
diff --git a/data/reusables/discussions/marking-a-comment-as-an-answer.md b/data/reusables/discussions/marking-a-comment-as-an-answer.md
new file mode 100644
index 000000000000..2073ccb930c7
--- /dev/null
+++ b/data/reusables/discussions/marking-a-comment-as-an-answer.md
@@ -0,0 +1,16 @@
+You can mark a comment in the discussion as an answer to the discussion if a discussion is within a category that accepts answers. For more information, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-categories-and-formats-for-discussions)."
+
+When you mark a question as an answer, {% data variables.product.product_name %} will highlight the comment and replies to the comment to help visitors quickly find the answer.
+
+
+
+You can't mark a threaded comment in response to a comment as the answer to a discussion. You also can't mark a minimized comment as the answer to a discussion.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+1. In the list of discussions, click the unanswered discussion you want to mark as answered.
+ 
+1. In the discussion, find the comment you want to mark as the answer.
+1. In the upper-right corner of the comment, click {% octicon "check-circle" aria-label="The circular check icon" %}.
+ 
+1. Optionally, to unmark a comment as the answer, click {% octicon "check-circle-fill" aria-label="The filled circular check icon" %}.
diff --git a/data/reusables/discussions/repository-category-limit.md b/data/reusables/discussions/repository-category-limit.md
new file mode 100644
index 000000000000..293d3632b5fd
--- /dev/null
+++ b/data/reusables/discussions/repository-category-limit.md
@@ -0,0 +1 @@
+Each repository can have up to 10 categories.
diff --git a/data/reusables/discussions/starting-a-discussion.md b/data/reusables/discussions/starting-a-discussion.md
new file mode 100644
index 000000000000..f4531e36de4e
--- /dev/null
+++ b/data/reusables/discussions/starting-a-discussion.md
@@ -0,0 +1,10 @@
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.discussions.discussions-tab %}
+1. Click **New discussion**.
+ 
+1. Select the **Select Category** drop-down menu, and click a category for your discussion.
+ 
+1. Type a title and body for your discussion.
+ 
+1. Click **Start discussion**.
+ 
diff --git a/data/reusables/discussions/you-can-categorize-discussions.md b/data/reusables/discussions/you-can-categorize-discussions.md
new file mode 100644
index 000000000000..bb05316d772c
--- /dev/null
+++ b/data/reusables/discussions/you-can-categorize-discussions.md
@@ -0,0 +1 @@
+You can categorize discussions to help community members begin conversations in the right place, and to help community members find related discussions.
diff --git a/data/reusables/discussions/you-can-convert-an-issue.md b/data/reusables/discussions/you-can-convert-an-issue.md
new file mode 100644
index 000000000000..1421256e1f64
--- /dev/null
+++ b/data/reusables/discussions/you-can-convert-an-issue.md
@@ -0,0 +1 @@
+If an issue turns out to be a question or open-ended conversation instead of a work item to track and prioritize, you can convert the issue to a discussion.
diff --git a/data/reusables/discussions/you-can-use-discussions.md b/data/reusables/discussions/you-can-use-discussions.md
new file mode 100644
index 000000000000..27c1ba7cb227
--- /dev/null
+++ b/data/reusables/discussions/you-can-use-discussions.md
@@ -0,0 +1 @@
+You can use discussions to ask and answer questions, share information, make announcements, and conduct or participate in conversations about a project. For more information, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)."
\ No newline at end of file
diff --git a/data/reusables/discussions/you-cannot-convert-a-discussion.md b/data/reusables/discussions/you-cannot-convert-a-discussion.md
new file mode 100644
index 000000000000..9e9b687b6723
--- /dev/null
+++ b/data/reusables/discussions/you-cannot-convert-a-discussion.md
@@ -0,0 +1 @@
+You cannot convert a discussion to an issue.
\ No newline at end of file
diff --git a/data/reusables/education/about-github-education-link.md b/data/reusables/education/about-github-education-link.md
index 1d0ef762d6e0..67fa09ec6abc 100644
--- a/data/reusables/education/about-github-education-link.md
+++ b/data/reusables/education/about-github-education-link.md
@@ -1 +1 @@
-Before applying for an individual discount, check if your learning community is already partnered with us as a {% data variables.product.prodname_education %} school. For more information, see "[About {% data variables.product.prodname_education %}](https://education.github.com/partners/schools)."
+Before applying for an individual discount, check if your learning community is already partnered with us as a {% data variables.product.prodname_education %} school. For more information, see "[About {% data variables.product.prodname_education %}](/education/teach-and-learn-with-github-education/about-github-education)."
diff --git a/data/reusables/education/apply-for-team.md b/data/reusables/education/apply-for-team.md
index afc1ef555d69..88fdff7f90b4 100644
--- a/data/reusables/education/apply-for-team.md
+++ b/data/reusables/education/apply-for-team.md
@@ -1 +1 @@
-- Apply for free [{% data variables.product.prodname_team %}](/articles/github-s-products), which allows unlimited users and private repositories. For more information, see "[Applying for an educator or researcher discount](/articles/applying-for-an-educator-or-researcher-discount)."
+- Apply for free [{% data variables.product.prodname_team %}](/articles/github-s-products), which allows unlimited users and private repositories. For more information, see "[Apply for an educator or researcher discount](/education/teach-and-learn-with-github-education/apply-for-an-educator-or-researcher-discount)."
diff --git a/data/reusables/education/click-get-teacher-benefits.md b/data/reusables/education/click-get-teacher-benefits.md
new file mode 100644
index 000000000000..bb42c5f8d552
--- /dev/null
+++ b/data/reusables/education/click-get-teacher-benefits.md
@@ -0,0 +1,2 @@
+1. Under "Individuals", click **Get teacher benefits**.
+ 
diff --git a/data/reusables/education/educator-requirements.md b/data/reusables/education/educator-requirements.md
new file mode 100644
index 000000000000..b7a004744d78
--- /dev/null
+++ b/data/reusables/education/educator-requirements.md
@@ -0,0 +1,6 @@
+To apply for an educator or researcher discount, you must meet the following requirements.
+
+- Be an educator, faculty member, or researcher.
+- Have a verifiable school-issued email address.
+- Upload documents that prove your school affiliation.
+- Have a user account on {% data variables.product.product_name %}.
diff --git a/data/reusables/gated-features/discussions.md b/data/reusables/gated-features/discussions.md
new file mode 100644
index 000000000000..5ada0a25eea1
--- /dev/null
+++ b/data/reusables/gated-features/discussions.md
@@ -0,0 +1 @@
+{% data variables.product.prodname_discussions %} is available in beta for public repositories on {% data variables.product.prodname_dotcom_the_website %}. {% data reusables.gated-features.more-info-org-products %}
diff --git a/data/reusables/marketplace/app-transfer-to-org-for-verification.md b/data/reusables/marketplace/app-transfer-to-org-for-verification.md
new file mode 100644
index 000000000000..0621a9e6e919
--- /dev/null
+++ b/data/reusables/marketplace/app-transfer-to-org-for-verification.md
@@ -0,0 +1 @@
+If you want to sell an app that's owned by your user account, first you'll need to transfer the app to an organization, and then request verification for a listing created by the organization.
diff --git a/data/reusables/marketplace/free-plan-note.md b/data/reusables/marketplace/free-plan-note.md
new file mode 100644
index 000000000000..bf63caa53df4
--- /dev/null
+++ b/data/reusables/marketplace/free-plan-note.md
@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** If you're listing an app on {% data variables.product.prodname_marketplace %}, you can't list your app with a free pricing plan if you offer a paid service outside of {% data variables.product.prodname_marketplace %}.
+
+{% endnote %}
diff --git a/data/reusables/marketplace/launch-with-free.md b/data/reusables/marketplace/launch-with-free.md
index 15230e218b5e..2151c241cce9 100644
--- a/data/reusables/marketplace/launch-with-free.md
+++ b/data/reusables/marketplace/launch-with-free.md
@@ -1 +1 @@
-You can submit both an unverified and verified app. This will allow you to launch with a free version of your app. Once GitHub verifies your app, your listing will change from unverified to verified in {% data variables.product.prodname_marketplace %} and GitHub will publish your new pricing plans.
+You can request publication with or without verification. Requesting publication without verification allows you to launch a free version of your app quickly. If you then request publication with verification, your listing will be updated to include the verified creator badge and any paid pricing plans when you complete verification and financial onboarding.
diff --git a/data/reusables/marketplace/marketplace-billing-ui-requirements.md b/data/reusables/marketplace/marketplace-billing-ui-requirements.md
index 9c02badeae41..5aa91ca83994 100644
--- a/data/reusables/marketplace/marketplace-billing-ui-requirements.md
+++ b/data/reusables/marketplace/marketplace-billing-ui-requirements.md
@@ -1,7 +1,7 @@
-- Customers who cancel a paid plan purchased from {% data variables.product.prodname_marketplace %} must be automatically downgraded to the app's free plan if it exists. {% data reusables.marketplace.cancellation-clarification %} It's highly recommended to allow customers to re-enable their previous plan.
-- Customers must be able to upgrade from your app's UI if you provide an [upgrade URL](/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans/#about-upgrade-urls) in this format: `https://www.github.com/marketplace/
+
+
All {{ product.title }} docs
@@ -14,18 +14,15 @@ {{ categ
{{ categ
{% for maptopic in category[1].maptopics %}
{% unless maptopic[1].hidden %}
- {% assign numArticles = maptopic[1].articles | obj_size %}
- -
- {{ maptopic[1].title }}
-
- {% if numArticles > maxArticles %}
-
- {% endif %}
+ {% assign numArticles = category[1].maptopics | obj_size %}
+
-
+
+ {{ maptopic[1].title }}
+
+ {% if numArticles > maxArticles %}
+
+ {% endif %}
{% endunless %}
{% endfor %}
diff --git a/includes/code-example-card.html b/includes/code-example-card.html
index a1a1d8c5be15..9de7d38aeea5 100644
--- a/includes/code-example-card.html
+++ b/includes/code-example-card.html
@@ -1,4 +1,4 @@
-
+
diff --git a/javascripts/filter-cards.js b/javascripts/filter-cards.js
new file mode 100644
index 000000000000..986322b7ae25
--- /dev/null
+++ b/javascripts/filter-cards.js
@@ -0,0 +1,90 @@
+function filterCards (cards, value) {
+ const noResults = document.querySelector('.js-filter-card-no-results')
+ const matchReg = new RegExp(value, 'i')
+
+ // Track whether or not we had at least one match
+ let hasMatches = false
+
+ for (let index = 0; index < cards.length; index++) {
+ const card = cards[index]
+
+ // Filter was emptied
+ if (!value) {
+ // Make sure we don't show the "No results" blurb
+ hasMatches = true
+
+ // Hide all but the first 6
+ if (index > 5) {
+ card.classList.add('d-none')
+ } else {
+ card.classList.remove('d-none')
+ }
+
+ continue
+ }
+
+ // Check if this card matches - any `data-*` attribute contains the string
+ const cardMatches = Object.keys(card.dataset)
+ .some(key => matchReg.test(card.dataset[key]))
+
+ if (cardMatches) {
+ card.classList.remove('d-none')
+ hasMatches = true
+ } else {
+ card.classList.add('d-none')
+ }
+ }
+
+ // If there wasn't at least one match, show the "no results" text
+ if (!hasMatches) {
+ document.querySelector('.js-filter-card-value').textContent = value
+ noResults.classList.remove('d-none')
+ } else {
+ noResults.classList.add('d-none')
+ }
+}
+
+export default function filterCodeExamples () {
+ const filter = document.querySelector('.js-filter-card-filter')
+ const cards = Array.from(document.querySelectorAll('.js-filter-card'))
+ const showMoreButton = document.querySelector('.js-filter-card-show-more')
+
+ if (filter) {
+ filter.addEventListener('keyup', evt => {
+ const value = evt.currentTarget.value
+
+ // Show or hide the "Show more" button if there is a value
+ if (value) showMoreButton.classList.add('d-none')
+ else showMoreButton.classList.remove('d-none')
+
+ filterCards(cards, value)
+ })
+ }
+
+ if (showMoreButton) {
+ showMoreButton.addEventListener('click', evt => {
+ // Number of cards that are currently visible
+ const numShown = cards.filter(card => !card.classList.contains('d-none')).length
+ // We want to show 6 more
+ const totalToShow = numShown + 6
+
+ for (let index = numShown; index < cards.length; index++) {
+ const card = cards[index]
+
+ // If the card we're at is less than the total number of cards
+ // we should show, show this one
+ if (index < totalToShow) {
+ card.classList.remove('d-none')
+ } else {
+ // Otherwise, we've shown the ones we intend to so exit the loop
+ break
+ }
+ }
+
+ // They're all shown now, we should hide the button
+ if (totalToShow >= cards.length) {
+ evt.currentTarget.style.display = 'none'
+ }
+ })
+ }
+}
diff --git a/javascripts/filter-code-examples.js b/javascripts/filter-code-examples.js
deleted file mode 100644
index c6592672e418..000000000000
--- a/javascripts/filter-code-examples.js
+++ /dev/null
@@ -1,92 +0,0 @@
-function filterCards (cards, value) {
- const noResults = document.querySelector('.js-code-example-no-results')
- const matchReg = new RegExp(value, 'i')
-
- // Track whether or not we had at least one match
- let hasMatches = false
-
- for (let index = 0; index < cards.length; index++) {
- const card = cards[index]
-
- // Filter was emptied
- if (!value) {
- // Make sure we don't show the "No results" blurb
- hasMatches = true
-
- // Hide all but the first 6
- if (index > 5) {
- card.classList.add('d-none')
- } else {
- card.classList.remove('d-none')
- }
-
- continue
- }
-
- // Check if this card matches
- const { title, description, tags } = card.dataset
- const cardMatches = (
- matchReg.test(title) ||
- matchReg.test(description) ||
- matchReg.test(tags)
- )
-
- if (cardMatches) {
- card.classList.remove('d-none')
- hasMatches = true
- } else {
- card.classList.add('d-none')
- }
- }
-
- // If there wasn't at least one match, show the "no results" text
- if (!hasMatches) {
- document.querySelector('.js-code-example-filter-value').textContent = value
- noResults.classList.remove('d-none')
- } else {
- noResults.classList.add('d-none')
- }
-}
-
-export default function filterCodeExamples () {
- const filter = document.querySelector('.js-code-example-filter')
- if (!filter) return
-
- const cards = Array.from(document.querySelectorAll('.js-code-example-card'))
- const showMoreButton = document.querySelector('.js-code-example-show-more')
-
- filter.addEventListener('keyup', evt => {
- const value = evt.currentTarget.value
-
- // Show or hide the "Show more" button if there is a value
- if (value) showMoreButton.classList.add('d-none')
- else showMoreButton.classList.remove('d-none')
-
- filterCards(cards, value)
- })
-
- showMoreButton.addEventListener('click', evt => {
- // Number of cards that are currently visible
- const numShown = cards.filter(card => !card.classList.contains('d-none')).length
- // We want to show 6 more
- const totalToShow = numShown + 6
-
- for (let index = numShown; index < cards.length; index++) {
- const card = cards[index]
-
- // If the card we're at is less than the total number of cards
- // we should show, show this one
- if (index < totalToShow) {
- card.classList.remove('d-none')
- } else {
- // Otherwise, we've shown the ones we intend to so exit the loop
- break
- }
- }
-
- // They're all shown now, we should hide the button
- if (totalToShow === cards.length) {
- evt.currentTarget.style.display = 'none'
- }
- })
-}
diff --git a/javascripts/index.js b/javascripts/index.js
index c1f83b947d7e..034701bdfd2d 100644
--- a/javascripts/index.js
+++ b/javascripts/index.js
@@ -14,7 +14,7 @@ import experiment from './experiment'
import copyCode from './copy-code'
import { fillCsrf } from './get-csrf'
import initializeEvents from './events'
-import filterCodeExamples from './filter-code-examples'
+import filterCards from './filter-cards'
import allArticles from './all-articles'
import devToc from './dev-toc'
@@ -29,7 +29,7 @@ document.addEventListener('DOMContentLoaded', async () => {
print()
localization()
copyCode()
- filterCodeExamples()
+ filterCards()
allArticles()
devToc()
await fillCsrf() // this must complete before any POST calls
diff --git a/layouts/product-landing.html b/layouts/product-landing.html
index 99a3a491875b..9a4360aaf314 100644
--- a/layouts/product-landing.html
+++ b/layouts/product-landing.html
@@ -12,16 +12,30 @@
Product
- {{ page.shortTitle }}
+
+ {{ page.shortTitle }}
+
+ {% if page.beta_product %}
+ Beta
+ {% endif %}
+
{{ page.intro }}
{% data ui.product_landing.quick_start %}
-
- {% data ui.product_landing.reference_guides %}
-
+ {% if page.introLinks.reference %}
+
+ {% data ui.product_landing.reference_guides %}
+
+ {% endif %}
+
+ {% if page.introLinks.overview %}
+
+ {% data ui.product_landing.overview %}
+
+ {% endif %}
{% if page.product_video %}
@@ -40,7 +54,7 @@ {{ page.shortTitle }}
-
+
{% data ui.toc.guides %}
View all {% octicon "arrow-right" height="14" class="v-align-middle" %}
@@ -57,7 +71,7 @@ {{ link.title }}
+
{% data ui.toc.popular_articles %}
@@ -72,25 +86,27 @@ {{ link.title }}
-
-
- {% data ui.toc.whats_new %}
- View all {% octicon "arrow-right" height="14" class="v-align-middle" %}
+ {% if page.changelog %}
+
+
+ {% data ui.toc.whats_new %}
+ View all {% octicon "arrow-right" height="14" class="v-align-middle" %}
+
+
+ {% for link in page.changelog %}
+ -
+
+
{{ link.title }} →
+
+
+
+ {% endfor %}
+
-
- {% for link in page.changelog %}
- -
-
-
{{ link.title }} →
-
-
-
- {% endfor %}
-
-
+ {% endif %}
{{ renderedPage }}
diff --git a/lib/frontmatter.js b/lib/frontmatter.js
index 9e9e3a0438e0..fa668f48a8ca 100644
--- a/lib/frontmatter.js
+++ b/lib/frontmatter.js
@@ -57,7 +57,8 @@ const schema = {
type: 'object',
properties: {
quickstart: { type: 'string' },
- reference: { type: 'string' }
+ reference: { type: 'string' },
+ overview: { type: 'string' }
}
},
authors: {
@@ -88,6 +89,10 @@ const schema = {
}
}
},
+ // Used in `product-landing.html`
+ beta_product: {
+ type: 'boolean'
+ },
// Show in `product-landing.html`
product_video: {
type: 'string',
diff --git a/lib/page.js b/lib/page.js
index c282f1792fd1..f9274f0119e8 100644
--- a/lib/page.js
+++ b/lib/page.js
@@ -1,5 +1,5 @@
const assert = require('assert')
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
const cheerio = require('cheerio')
const patterns = require('./patterns')
@@ -23,15 +23,30 @@ const slash = require('slash')
const statsd = require('./statsd')
class Page {
- constructor (opts) {
+ static async init (opts) {
assert(opts.relativePath, 'relativePath is required')
assert(opts.basePath, 'basePath is required')
+
+ const relativePath = slash(opts.relativePath)
+ const fullPath = slash(path.join(opts.basePath, relativePath))
+ const raw = await fs.readFile(fullPath, 'utf8')
+
+ return new Page({ ...opts, relativePath, fullPath, raw })
+ }
+
+ static async exists (path) {
+ try {
+ return await fs.stat(path)
+ } catch (err) {
+ if (err.code === 'ENOENT') return false
+ console.error(err)
+ }
+ }
+
+ constructor (opts) {
assert(opts.languageCode, 'languageCode is required')
Object.assign(this, { ...opts })
- this.relativePath = slash(this.relativePath)
- this.fullPath = slash(path.join(this.basePath, this.relativePath))
- this.raw = fs.readFileSync(this.fullPath, 'utf8')
// TODO remove this when crowdin-support issue 66 has been resolved
if (this.languageCode !== 'en' && this.raw.includes(': verdadero')) {
diff --git a/lib/pages.js b/lib/pages.js
index cdca1fae1e2a..4db70e7dd5cb 100644
--- a/lib/pages.js
+++ b/lib/pages.js
@@ -2,42 +2,50 @@ const path = require('path')
const walk = require('walk-sync').entries
const Page = require('./page')
const languages = require('./languages')
-const fs = require('fs')
+const { mapLimit, filterLimit } = require('async')
+const FILE_READ_LIMIT = 500
async function loadPageList () {
const pageList = []
// load english pages
const englishPath = path.join(__dirname, '..', languages.en.dir, 'content')
- const englishPages = walk(englishPath)
- .filter(({ relativePath }) => {
- return relativePath.endsWith('.md') &&
- !relativePath.includes('README')
- })
- .map(fileData => new Page({ ...fileData, languageCode: languages.en.code }))
-
+ const englishPaths = walk(englishPath)
+ .filter(({ relativePath }) =>
+ relativePath.endsWith('.md') && !relativePath.includes('README')
+ )
+ const englishPages = await mapLimit(
+ englishPaths,
+ FILE_READ_LIMIT,
+ async fileData => await Page.init({ ...fileData, languageCode: languages.en.code })
+ )
pageList.push(...englishPages)
// load matching pages in other languages
- for (const page of englishPages) {
- for (const language of Object.values(languages)) {
- if (language.code === 'en') continue
-
+ let localizedPaths = Object.values(languages)
+ .filter(({ code }) => code !== 'en')
+ .map(language => {
const basePath = path.join(__dirname, '..', language.dir, 'content')
- const localizedPath = path.join(basePath, page.relativePath)
- try {
- fs.statSync(localizedPath)
- } catch (_) {
- continue
- }
-
- pageList.push(new Page({
- relativePath: page.relativePath,
+ return englishPages.map(page => ({
basePath,
+ relativePath: page.relativePath,
+ localizedPath: path.join(basePath, page.relativePath),
languageCode: language.code
}))
- }
- }
+ })
+ .flat()
+ localizedPaths = await filterLimit(
+ localizedPaths,
+ FILE_READ_LIMIT,
+ async ({ localizedPath }) => Page.exists(localizedPath)
+ )
+ const localizedPages = await mapLimit(
+ localizedPaths,
+ FILE_READ_LIMIT,
+ async ({ basePath, relativePath, languageCode }) =>
+ await Page.init({ basePath, relativePath, languageCode })
+ )
+ pageList.push(...localizedPages)
return pageList
}
diff --git a/lib/rest/static/decorated/api.github.com.json b/lib/rest/static/decorated/api.github.com.json
index e2f389b736df..f5234c81ccac 100644
--- a/lib/rest/static/decorated/api.github.com.json
+++ b/lib/rest/static/decorated/api.github.com.json
@@ -5975,6 +5975,123 @@
"bodyParameters": [],
"descriptionHTML": "Forces the removal of a self-hosted runner from an enterprise. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.
\nYou must authenticate using an access token with the admin:enterprise scope to use this endpoint.
"
},
+ {
+ "verb": "get",
+ "requestPath": "/enterprises/{enterprise}/audit-log",
+ "serverUrl": "https://api.github.com",
+ "parameters": [
+ {
+ "name": "enterprise",
+ "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.
"
+ },
+ {
+ "name": "phrase",
+ "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A search phrase. For more information, see Searching the audit log.
"
+ },
+ {
+ "name": "include",
+ "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "enum": [
+ "web",
+ "git",
+ "all"
+ ]
+ },
+ "descriptionHTML": "The event types to include:
\n\nweb - returns web (non-Git) eventsgit - returns Git eventsall - returns both web and Git events
\nThe default is web.
"
+ },
+ {
+ "name": "after",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.
"
+ },
+ {
+ "name": "before",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.
"
+ },
+ {
+ "name": "per_page",
+ "description": "Results per page (max 100)",
+ "in": "query",
+ "schema": {
+ "type": "integer",
+ "default": 30
+ },
+ "descriptionHTML": "Results per page (max 100)
"
+ }
+ ],
+ "x-codeSamples": [
+ {
+ "lang": "Shell",
+ "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/enterprises/ENTERPRISE/audit-log",
+ "html": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/enterprises/ENTERPRISE/audit-log
"
+ },
+ {
+ "lang": "JavaScript",
+ "source": "await octokit.request('GET /enterprises/{enterprise}/audit-log', {\n enterprise: 'enterprise'\n})",
+ "html": "await octokit.request('GET /enterprises/{enterprise}/audit-log', {\n enterprise: 'enterprise'\n})\n
"
+ }
+ ],
+ "summary": "Get the audit log for an enterprise",
+ "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the `admin:enterprise` scope.",
+ "operationId": "audit-log/get-audit-log",
+ "tags": [
+ "audit-log"
+ ],
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/enterprise-admin#get-the-audit-log-for-an-enterprise"
+ },
+ "x-github": {
+ "githubCloudOnly": true,
+ "enabledForGitHubApps": false,
+ "previews": [],
+ "category": "enterprise-admin",
+ "subcategory": "audit-log"
+ },
+ "slug": "get-the-audit-log-for-an-enterprise",
+ "category": "enterprise-admin",
+ "categoryLabel": "Enterprise admin",
+ "subcategory": "audit-log",
+ "subcategoryLabel": "Audit log",
+ "notes": [],
+ "bodyParameters": [],
+ "descriptionHTML": "Note: The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.
\nGets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the admin:enterprise scope.
",
+ "responses": [
+ {
+ "httpStatusCode": "200",
+ "httpStatusMessage": "OK",
+ "description": "Default response",
+ "payload": "[\n {\n \"@timestamp\": 1606929874512,\n \"action\": \"team.add_member\",\n \"actor\": \"octocat\",\n \"created_at\": 1606929874512,\n \"org\": \"octo-corp\",\n \"team\": \"octo-corp/example-team\",\n \"user\": \"monalisa\"\n },\n {\n \"@timestamp\": 1606507117008,\n \"action\": \"org.create\",\n \"actor\": \"octocat\",\n \"created_at\": 1606507117008,\n \"org\": \"octocat-test-org\"\n },\n {\n \"@timestamp\": 1605719148837,\n \"action\": \"repo.destroy\",\n \"actor\": \"monalisa\",\n \"created_at\": 1605719148837,\n \"org\": \"mona-org\",\n \"repo\": \"mona-org/mona-test-repo\",\n \"visibility\": \"private\"\n }\n]\n
"
+ }
+ ]
+ },
{
"verb": "get",
"requestPath": "/enterprises/{enterprise}/settings/billing/actions",
@@ -14225,6 +14342,120 @@
"bodyParameters": [],
"descriptionHTML": "Removes a repository from an organization secret when the visibility for repository access is set to selected. The visibility is set when you Create or update an organization secret. You must authenticate using an access token with the admin:org scope to use this endpoint. GitHub Apps must have the secrets organization permission to use this endpoint.
"
},
+ {
+ "verb": "get",
+ "requestPath": "/orgs/{org}/audit-log",
+ "serverUrl": "https://api.github.com",
+ "parameters": [
+ {
+ "name": "org",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": ""
+ },
+ {
+ "name": "phrase",
+ "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A search phrase. For more information, see Searching the audit log.
"
+ },
+ {
+ "name": "include",
+ "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "enum": [
+ "web",
+ "git",
+ "all"
+ ]
+ },
+ "descriptionHTML": "The event types to include:
\n\nweb - returns web (non-Git) eventsgit - returns Git eventsall - returns both web and Git events
\nThe default is web.
"
+ },
+ {
+ "name": "after",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.
"
+ },
+ {
+ "name": "before",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.
"
+ },
+ {
+ "name": "per_page",
+ "description": "Results per page (max 100)",
+ "in": "query",
+ "schema": {
+ "type": "integer",
+ "default": 30
+ },
+ "descriptionHTML": "Results per page (max 100)
"
+ }
+ ],
+ "x-codeSamples": [
+ {
+ "lang": "Shell",
+ "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/orgs/ORG/audit-log",
+ "html": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/orgs/ORG/audit-log
"
+ },
+ {
+ "lang": "JavaScript",
+ "source": "await octokit.request('GET /orgs/{org}/audit-log', {\n org: 'org'\n})",
+ "html": "await octokit.request('GET /orgs/{org}/audit-log', {\n org: 'org'\n})\n
"
+ }
+ ],
+ "summary": "Get the audit log for an organization",
+ "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an organization. For more information, see \"[Reviewing the audit log for your organization](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization).\"\n\nTo use this endpoint, you must be an organization owner, and you must use an access token with the `admin:org` scope. GitHub Apps must have the `organization_administration` read permission to use this endpoint.",
+ "operationId": "orgs/get-audit-log",
+ "tags": [
+ "orgs"
+ ],
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/orgs#get-the-audit-log-for-an-organization"
+ },
+ "x-github": {
+ "githubCloudOnly": true,
+ "enabledForGitHubApps": true,
+ "previews": [],
+ "category": "orgs",
+ "subcategory": null
+ },
+ "slug": "get-the-audit-log-for-an-organization",
+ "category": "orgs",
+ "categoryLabel": "Orgs",
+ "notes": [],
+ "bodyParameters": [],
+ "descriptionHTML": "Note: The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.
\nGets the audit log for an organization. For more information, see \"Reviewing the audit log for your organization.\"
\nTo use this endpoint, you must be an organization owner, and you must use an access token with the admin:org scope. GitHub Apps must have the organization_administration read permission to use this endpoint.
",
+ "responses": [
+ {
+ "httpStatusCode": "200",
+ "httpStatusMessage": "OK",
+ "description": "Default response",
+ "payload": "[\n {\n \"@timestamp\": 1606929874512,\n \"action\": \"team.add_member\",\n \"actor\": \"octocat\",\n \"created_at\": 1606929874512,\n \"org\": \"octo-corp\",\n \"team\": \"octo-corp/example-team\",\n \"user\": \"monalisa\"\n },\n {\n \"@timestamp\": 1606507117008,\n \"action\": \"org.create\",\n \"actor\": \"octocat\",\n \"created_at\": 1606507117008,\n \"org\": \"octocat-test-org\"\n },\n {\n \"@timestamp\": 1605719148837,\n \"action\": \"repo.destroy\",\n \"actor\": \"monalisa\",\n \"created_at\": 1605719148837,\n \"org\": \"mona-org\",\n \"repo\": \"mona-org/mona-test-repo\",\n \"visibility\": \"private\"\n }\n]\n
"
+ }
+ ]
+ },
{
"verb": "get",
"requestPath": "/orgs/{org}/blocks",
diff --git a/lib/rest/static/dereferenced/api.github.com.deref.json b/lib/rest/static/dereferenced/api.github.com.deref.json
index 873643c5bcd5..7dbc79d26958 100644
--- a/lib/rest/static/dereferenced/api.github.com.deref.json
+++ b/lib/rest/static/dereferenced/api.github.com.deref.json
@@ -17051,6 +17051,254 @@
}
}
},
+ "/enterprises/{enterprise}/audit-log": {
+ "get": {
+ "summary": "Get the audit log for an enterprise",
+ "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the `admin:enterprise` scope.",
+ "operationId": "audit-log/get-audit-log",
+ "tags": [
+ "audit-log"
+ ],
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/enterprise-admin#get-the-audit-log-for-an-enterprise"
+ },
+ "parameters": [
+ {
+ "name": "enterprise",
+ "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "phrase",
+ "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "include",
+ "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "enum": [
+ "web",
+ "git",
+ "all"
+ ]
+ }
+ },
+ {
+ "name": "after",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "before",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "per_page",
+ "description": "Results per page (max 100)",
+ "in": "query",
+ "schema": {
+ "type": "integer",
+ "default": 30
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "@timestamp": {
+ "type": "integer",
+ "description": "The time the audit log event occurred, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)."
+ },
+ "action": {
+ "type": "string",
+ "description": "The name of the action that was performed, for example `user.login` or `repo.create`."
+ },
+ "active": {
+ "type": "boolean"
+ },
+ "active_was": {
+ "type": "boolean"
+ },
+ "actor": {
+ "type": "string",
+ "description": "The actor who performed the action."
+ },
+ "blocked_user": {
+ "type": "string",
+ "description": "The username of the account being blocked."
+ },
+ "business": {
+ "type": "string"
+ },
+ "config": {
+ "type": "array"
+ },
+ "config_was": {
+ "type": "array"
+ },
+ "content_type": {
+ "type": "string"
+ },
+ "created_at": {
+ "type": "integer",
+ "description": "The time the audit log event was recorded, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)."
+ },
+ "deploy_key_fingerprint": {
+ "type": "string"
+ },
+ "emoji": {
+ "type": "string"
+ },
+ "events": {
+ "type": "array"
+ },
+ "events_were": {
+ "type": "array"
+ },
+ "explanation": {
+ "type": "string"
+ },
+ "fingerprint": {
+ "type": "string"
+ },
+ "hook_id": {
+ "type": "integer"
+ },
+ "limited_availability": {
+ "type": "boolean"
+ },
+ "message": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "old_user": {
+ "type": "string"
+ },
+ "openssh_public_key": {
+ "type": "string"
+ },
+ "org": {
+ "type": "string"
+ },
+ "previous_visibility": {
+ "type": "string"
+ },
+ "read_only": {
+ "type": "boolean"
+ },
+ "repo": {
+ "type": "string",
+ "description": "The name of the repository."
+ },
+ "repository": {
+ "type": "string",
+ "description": "The name of the repository."
+ },
+ "repository_public": {
+ "type": "boolean"
+ },
+ "target_login": {
+ "type": "string"
+ },
+ "team": {
+ "type": "string"
+ },
+ "transport_protocol": {
+ "type": "integer",
+ "description": "The type of protocol (for example, HTTP or SSH) used to transfer Git data."
+ },
+ "transport_protocol_name": {
+ "type": "string",
+ "description": "A human readable name for the protocol (for example, HTTP or SSH) used to transfer Git data."
+ },
+ "user": {
+ "type": "string",
+ "description": "The user that was affected by the action performed (if available)."
+ },
+ "visibility": {
+ "type": "string",
+ "description": "The repository visibility, for example `public` or `private`."
+ }
+ }
+ }
+ },
+ "examples": {
+ "default": {
+ "value": [
+ {
+ "@timestamp": 1606929874512,
+ "action": "team.add_member",
+ "actor": "octocat",
+ "created_at": 1606929874512,
+ "org": "octo-corp",
+ "team": "octo-corp/example-team",
+ "user": "monalisa"
+ },
+ {
+ "@timestamp": 1606507117008,
+ "action": "org.create",
+ "actor": "octocat",
+ "created_at": 1606507117008,
+ "org": "octocat-test-org"
+ },
+ {
+ "@timestamp": 1605719148837,
+ "action": "repo.destroy",
+ "actor": "monalisa",
+ "created_at": 1605719148837,
+ "org": "mona-org",
+ "repo": "mona-org/mona-test-repo",
+ "visibility": "private"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "x-github": {
+ "githubCloudOnly": true,
+ "enabledForGitHubApps": false,
+ "previews": [
+
+ ],
+ "category": "enterprise-admin",
+ "subcategory": "audit-log"
+ }
+ }
+ },
"/enterprises/{enterprise}/settings/billing/actions": {
"get": {
"summary": "Get GitHub Actions billing for an enterprise",
@@ -49105,6 +49353,253 @@
}
}
},
+ "/orgs/{org}/audit-log": {
+ "get": {
+ "summary": "Get the audit log for an organization",
+ "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an organization. For more information, see \"[Reviewing the audit log for your organization](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization).\"\n\nTo use this endpoint, you must be an organization owner, and you must use an access token with the `admin:org` scope. GitHub Apps must have the `organization_administration` read permission to use this endpoint.",
+ "operationId": "orgs/get-audit-log",
+ "tags": [
+ "orgs"
+ ],
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/orgs#get-the-audit-log-for-an-organization"
+ },
+ "parameters": [
+ {
+ "name": "org",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "phrase",
+ "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "include",
+ "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "enum": [
+ "web",
+ "git",
+ "all"
+ ]
+ }
+ },
+ {
+ "name": "after",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "before",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "per_page",
+ "description": "Results per page (max 100)",
+ "in": "query",
+ "schema": {
+ "type": "integer",
+ "default": 30
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "@timestamp": {
+ "type": "integer",
+ "description": "The time the audit log event occurred, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)."
+ },
+ "action": {
+ "type": "string",
+ "description": "The name of the action that was performed, for example `user.login` or `repo.create`."
+ },
+ "active": {
+ "type": "boolean"
+ },
+ "active_was": {
+ "type": "boolean"
+ },
+ "actor": {
+ "type": "string",
+ "description": "The actor who performed the action."
+ },
+ "blocked_user": {
+ "type": "string",
+ "description": "The username of the account being blocked."
+ },
+ "business": {
+ "type": "string"
+ },
+ "config": {
+ "type": "array"
+ },
+ "config_was": {
+ "type": "array"
+ },
+ "content_type": {
+ "type": "string"
+ },
+ "created_at": {
+ "type": "integer",
+ "description": "The time the audit log event was recorded, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)."
+ },
+ "deploy_key_fingerprint": {
+ "type": "string"
+ },
+ "emoji": {
+ "type": "string"
+ },
+ "events": {
+ "type": "array"
+ },
+ "events_were": {
+ "type": "array"
+ },
+ "explanation": {
+ "type": "string"
+ },
+ "fingerprint": {
+ "type": "string"
+ },
+ "hook_id": {
+ "type": "integer"
+ },
+ "limited_availability": {
+ "type": "boolean"
+ },
+ "message": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "old_user": {
+ "type": "string"
+ },
+ "openssh_public_key": {
+ "type": "string"
+ },
+ "org": {
+ "type": "string"
+ },
+ "previous_visibility": {
+ "type": "string"
+ },
+ "read_only": {
+ "type": "boolean"
+ },
+ "repo": {
+ "type": "string",
+ "description": "The name of the repository."
+ },
+ "repository": {
+ "type": "string",
+ "description": "The name of the repository."
+ },
+ "repository_public": {
+ "type": "boolean"
+ },
+ "target_login": {
+ "type": "string"
+ },
+ "team": {
+ "type": "string"
+ },
+ "transport_protocol": {
+ "type": "integer",
+ "description": "The type of protocol (for example, HTTP or SSH) used to transfer Git data."
+ },
+ "transport_protocol_name": {
+ "type": "string",
+ "description": "A human readable name for the protocol (for example, HTTP or SSH) used to transfer Git data."
+ },
+ "user": {
+ "type": "string",
+ "description": "The user that was affected by the action performed (if available)."
+ },
+ "visibility": {
+ "type": "string",
+ "description": "The repository visibility, for example `public` or `private`."
+ }
+ }
+ }
+ },
+ "examples": {
+ "default": {
+ "value": [
+ {
+ "@timestamp": 1606929874512,
+ "action": "team.add_member",
+ "actor": "octocat",
+ "created_at": 1606929874512,
+ "org": "octo-corp",
+ "team": "octo-corp/example-team",
+ "user": "monalisa"
+ },
+ {
+ "@timestamp": 1606507117008,
+ "action": "org.create",
+ "actor": "octocat",
+ "created_at": 1606507117008,
+ "org": "octocat-test-org"
+ },
+ {
+ "@timestamp": 1605719148837,
+ "action": "repo.destroy",
+ "actor": "monalisa",
+ "created_at": 1605719148837,
+ "org": "mona-org",
+ "repo": "mona-org/mona-test-repo",
+ "visibility": "private"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "x-github": {
+ "githubCloudOnly": true,
+ "enabledForGitHubApps": true,
+ "previews": [
+
+ ],
+ "category": "orgs",
+ "subcategory": null
+ }
+ }
+ },
"/orgs/{org}/blocks": {
"get": {
"summary": "List users blocked by an organization",
diff --git a/middleware/categories-for-support-team.js b/middleware/categories-for-support-team.js
index 7a38fb0cdea4..4b550a566efe 100644
--- a/middleware/categories-for-support-team.js
+++ b/middleware/categories-for-support-team.js
@@ -2,7 +2,7 @@
// to quickly search for Help articles by title and insert the link to
// the article into a reply to a customer.
const path = require('path')
-const fs = require('fs')
+const fs = require('fs').promises
const matter = require('gray-matter')
const dotcomDir = path.join(__dirname, '../content/github')
const dotcomIndex = path.join(dotcomDir, 'index.md')
@@ -10,24 +10,22 @@ const linkRegex = /{% (?:topic_)?link_in_list ?\/(.*?) ?%}/g
module.exports = async (req, res, next) => {
if (req.path !== '/categories.json') return next()
- const categories = generateCategories()
+ const categories = await generateCategories()
return res.json(categories)
}
-function generateCategories () {
+async function generateCategories () {
// get links included in dotcom index page.
// each link corresponds to a dotcom subdirectory
// example: getting-started-with-github
- const links = getLinks(fs.readFileSync(dotcomIndex, 'utf8'))
-
- const categories = []
+ const links = getLinks(await fs.readFile(dotcomIndex, 'utf8'))
// get links included in each subdir's index page
// these are links to articles
- links.forEach(link => {
+ const categories = await Promise.all(links.map(async link => {
const category = {}
const indexPath = getPath(link, 'index')
- const indexContents = fs.readFileSync(indexPath, 'utf8')
+ const indexContents = await fs.readFile(indexPath, 'utf8')
const { data, content } = matter(indexContents)
// get name from title frontmatter
@@ -36,29 +34,23 @@ function generateCategories () {
// get child article links
const articleLinks = getLinks(content)
- const publishedArticles = []
-
- articleLinks.forEach(articleLink => {
- const publishedArticle = {}
-
+ category.published_articles = (await Promise.all(articleLinks.map(async articleLink => {
// get title from frontmatter
const articlePath = getPath(link, articleLink)
- const articleContents = fs.readFileSync(articlePath, 'utf8')
+ const articleContents = await fs.readFile(articlePath, 'utf8')
const { data } = matter(articleContents)
// do not include map topics in list of published articles
if (data.mapTopic) return
- publishedArticle.title = data.title
- publishedArticle.slug = articleLink
-
- publishedArticles.push(publishedArticle)
- })
-
- category.published_articles = publishedArticles
+ return {
+ title: data.title,
+ slug: articleLink
+ }
+ }))).filter(Boolean)
- categories.push(category)
- })
+ return category
+ }))
return categories
}
diff --git a/package-lock.json b/package-lock.json
index b33963cf8bda..b0f2a9c3e7e9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -5577,8 +5577,7 @@
"async": {
"version": "3.2.0",
"resolved": "https://registry.npmjs.org/async/-/async-3.2.0.tgz",
- "integrity": "sha512-TR2mEZFVOj2pLStYxLht7TyfuRzaydfpxr3k9RpHIzMgw7A64dzsdqCxH1WJyQdoe8T10nDXd9wnEigmiuHIZw==",
- "dev": true
+ "integrity": "sha512-TR2mEZFVOj2pLStYxLht7TyfuRzaydfpxr3k9RpHIzMgw7A64dzsdqCxH1WJyQdoe8T10nDXd9wnEigmiuHIZw=="
},
"async-each": {
"version": "1.0.3",
diff --git a/package.json b/package.json
index a0663ce8fb91..a0cae4097a62 100644
--- a/package.json
+++ b/package.json
@@ -27,6 +27,7 @@
"@primer/css": "^15.1.0",
"@primer/octicons": "^11.0.0",
"algoliasearch": "^3.35.1",
+ "async": "^3.2.0",
"babel-loader": "^8.1.0",
"babel-preset-env": "^1.7.0",
"browser-date-formatter": "^3.0.3",
@@ -94,7 +95,6 @@
"devDependencies": {
"@actions/core": "^1.2.6",
"ajv": "^6.11.0",
- "async": "^3.2.0",
"await-sleep": "0.0.1",
"aws-sdk": "^2.610.0",
"babel-eslint": "^10.1.0",
diff --git a/script/check-s3-images.js b/script/check-s3-images.js
index 00ef528b7cda..6c83a4dc8a14 100755
--- a/script/check-s3-images.js
+++ b/script/check-s3-images.js
@@ -12,6 +12,7 @@ const patterns = require('../lib/patterns')
const authenticateToAWS = require('../lib/authenticate-to-aws.js')
const readlineSync = require('readline-sync')
const { execSync } = require('child_process')
+const enterpriseServerVersions = Object.keys(allVersions).filter(v => v.startsWith('enterprise-server@'))
const uploadScript = path.join(process.cwd(), 'script/upload-images-to-s3.js')
// ignore the non-enterprise default version
@@ -51,7 +52,8 @@ async function main () {
page,
site: siteData,
currentVersion: version,
- currentLanguage: 'en'
+ currentLanguage: 'en',
+ enterpriseServerVersions
}
const rendered = await renderContent(page.markdown, context)
diff --git a/server.js b/server.js
index 1af6650790b9..744d1fa924c3 100644
--- a/server.js
+++ b/server.js
@@ -16,8 +16,11 @@ if (!module.parent) {
// check that the development server is not already running
portUsed.check(port).then(async status => {
if (status === false) {
- // If in production, warm the server at the start
- if (process.env.NODE_ENV === 'production') warmServer()
+ // If in a deployed environment, warm the server at the start
+ if (process.env.NODE_ENV === 'production') {
+ // If in a production environment, wait for the cache to be fully warmed.
+ await warmServer()
+ }
// workaround for https://github.com/expressjs/express/issues/1101
const server = require('http').createServer(app)
diff --git a/tests/browser/browser.js b/tests/browser/browser.js
index 64fdb083ab33..aca6b864a720 100644
--- a/tests/browser/browser.js
+++ b/tests/browser/browser.js
@@ -3,6 +3,8 @@ const sleep = require('await-sleep')
const querystring = require('querystring')
describe('homepage', () => {
+ jest.setTimeout(60 * 1000)
+
test('should be titled "GitHub Documentation"', async () => {
await page.goto('http://localhost:4001')
await expect(page.title()).resolves.toMatch('GitHub Documentation')
@@ -10,6 +12,8 @@ describe('homepage', () => {
})
describe('algolia browser search', () => {
+ jest.setTimeout(60 * 1000)
+
it('works on the homepage', async () => {
await page.goto('http://localhost:4001/en')
await page.click('#search-input-container input[type="search"]')
diff --git a/tests/content/category-pages.js b/tests/content/category-pages.js
index 702c2d4c8c00..218301846ef1 100644
--- a/tests/content/category-pages.js
+++ b/tests/content/category-pages.js
@@ -42,15 +42,17 @@ describe('category pages', () => {
// Get links included in product index page.
// Each link corresponds to a product subdirectory (category).
// Example: "getting-started-with-github"
- const contents = fs.readFileSync(productIndex, 'utf8')
+ const contents = fs.readFileSync(productIndex, 'utf8') // TODO move to async
const { content } = matter(contents)
+ const productDir = path.dirname(productIndex)
+
const categoryLinks = getLinks(content)
- // HACK: I'm not really sure why this file is a one-off but it is...
- .filter(link => !(productName === 'actions' && link === 'quickstart'))
+ // Only include category directories, not standalone category files like content/actions/quickstart.md
+ .filter(link => fs.existsSync(getPath(productDir, link, 'index')))
+ // TODO this should move to async, but you can't asynchronously define tests with Jest...
// Map those to the Markdown file paths that represent that category page index
- const productDir = path.dirname(productIndex)
const categoryPaths = categoryLinks.map(link => getPath(productDir, link, 'index'))
// Make them relative for nicer display in test names
diff --git a/tests/content/crowdin-config.js b/tests/content/crowdin-config.js
index 63301e09935d..fd26e74b42e7 100644
--- a/tests/content/crowdin-config.js
+++ b/tests/content/crowdin-config.js
@@ -4,6 +4,8 @@ const ignoredPagePaths = config.files[0].ignore
const ignoredDataPaths = config.files[2].ignore
describe('crowdin.yml config file', () => {
+ jest.setTimeout(60 * 1000)
+
let pages
beforeAll(async (done) => {
pages = await loadPages()
diff --git a/tests/content/featured-links.js b/tests/content/featured-links.js
index c5b476153bcb..9829f1abd71a 100644
--- a/tests/content/featured-links.js
+++ b/tests/content/featured-links.js
@@ -45,8 +45,9 @@ describe('featuredLinks', () => {
test('featured links respect versioning', async () => {
const $ = await getDOM(`/en/enterprise/${enterpriseServerReleases.latest}/user/packages`)
- const $featuredLinks = $('.featured-links a')
+ const $featuredLinks = $('.all-articles-list a')
expect($featuredLinks.length).toBeGreaterThan(2)
+ expect($featuredLinks.text().includes('Package client guides for GitHub Packages')).toBe(true)
// does not include dotcom-only links
expect($featuredLinks.text().includes('About GitHub Container Registry')).toBe(false)
expect($featuredLinks.text().includes('Getting started with GitHub Container Registry')).toBe(false)
diff --git a/tests/content/glossary.js b/tests/content/glossary.js
index 3e3aea66f98d..3f278e501647 100644
--- a/tests/content/glossary.js
+++ b/tests/content/glossary.js
@@ -9,7 +9,10 @@ describe('glossaries', () => {
test('are broken into external, internal, and candidates', async () => {
const keys = Object.keys(glossaries)
- expect(keys).toEqual(['candidates', 'external', 'internal'])
+ expect(keys).toHaveLength(3)
+ expect(keys).toContain('candidates')
+ expect(keys).toContain('external')
+ expect(keys).toContain('internal')
})
test('every entry has a valid term', async () => {
diff --git a/tests/content/remove-liquid-statements.js b/tests/content/remove-liquid-statements.js
index 80fd02166945..f94dd5ae5cfa 100644
--- a/tests/content/remove-liquid-statements.js
+++ b/tests/content/remove-liquid-statements.js
@@ -1,4 +1,4 @@
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
const cheerio = require('cheerio')
const matter = require('gray-matter')
@@ -35,8 +35,8 @@ function processFrontmatter (contents, file) {
}
describe('removing liquid statements only', () => {
- test('removes liquid statements that specify "greater than version to deprecate"', () => {
- let contents = fs.readFileSync(greaterThan, 'utf8')
+ test('removes liquid statements that specify "greater than version to deprecate"', async () => {
+ let contents = await fs.readFile(greaterThan, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('Alpha')
@@ -57,8 +57,8 @@ Alpha\n\n{% else %}\n\nBravo\n\n{% if currentVersion ver_gt "enterprise-server@2
expect($('.example10').text().trim()).toBe('Alpha')
})
- test('removes liquid statements that specify "and greater than version to deprecate"', () => {
- let contents = fs.readFileSync(andGreaterThan1, 'utf8')
+ test('removes liquid statements that specify "and greater than version to deprecate"', async () => {
+ let contents = await fs.readFile(andGreaterThan1, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('{% if currentVersion != "free-pro-team@latest" %}\n\nAlpha\n\n{% endif %}')
@@ -71,8 +71,8 @@ Alpha\n\n{% if currentVersion != "free-pro-team@latest" %}\n\nBravo\n\n{% endif
Alpha\n\n{% if currentVersion ver_gt "enterprise-server@2.16" %}\n\nBravo\n\n{% endif %}\n\n{% endif %}`)
})
- test('removes liquid statements that specify "and greater than version to deprecate" (alternate format)', () => {
- let contents = fs.readFileSync(andGreaterThan2, 'utf8')
+ test('removes liquid statements that specify "and greater than version to deprecate" (alternate format)', async () => {
+ let contents = await fs.readFile(andGreaterThan2, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('{% if currentVersion ver_lt "enterprise-server@2.16" %}\n\nAlpha\n\n{% endif %}')
@@ -85,8 +85,8 @@ Alpha\n\n{% if currentVersion ver_lt "enterprise-server@2.16" %}\n\nBravo\n\n{%
Alpha\n\n{% if currentVersion != "free-pro-team@latest" %}\n\nBravo\n\n{% endif %}\n\n{% endif %}`)
})
- test('removes liquid statements that specify "not equals version to deprecate"', () => {
- let contents = fs.readFileSync(notEquals, 'utf8')
+ test('removes liquid statements that specify "not equals version to deprecate"', async () => {
+ let contents = await fs.readFile(notEquals, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('Alpha')
@@ -103,8 +103,8 @@ Alpha\n\n{% endif %}`)
})
describe('removing liquid statements and content', () => {
- test('removes interior content and liquid statements that specify "equals version to deprecate"', () => {
- let contents = fs.readFileSync(equals, 'utf8')
+ test('removes interior content and liquid statements that specify "equals version to deprecate"', async () => {
+ let contents = await fs.readFile(equals, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('')
@@ -117,8 +117,8 @@ Alpha\n\n{% else %}\n\nCharlie\n\n{% endif %}`)
expect($('.example6').text().trim()).toBe('Charlie\n\nBravo')
})
- test('removes interior content and liquid statements that specify "less than next oldest than version to deprecate"', () => {
- let contents = fs.readFileSync(lessThanNextOldest, 'utf8')
+ test('removes interior content and liquid statements that specify "less than next oldest than version to deprecate"', async () => {
+ let contents = await fs.readFile(lessThanNextOldest, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('Alpha')
@@ -137,8 +137,8 @@ Charlie\n\n{% else %}\n\nDelta\n\n{% endif %}\n\nEcho`)
})
describe('updating frontmatter', () => {
- test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to version to deprecate', () => {
- let contents = fs.readFileSync(frontmatter1, 'utf8')
+ test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to version to deprecate', async () => {
+ let contents = await fs.readFile(frontmatter1, 'utf8')
contents = processFrontmatter(contents, frontmatter1)
const $ = cheerio.load(contents)
// console.log('foo')
@@ -147,8 +147,8 @@ describe('updating frontmatter', () => {
expect($.text().includes('enterprise-server: \'>=2.13\'')).toBe(false)
})
- test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to next oldest version', () => {
- let contents = fs.readFileSync(frontmatter2, 'utf8')
+ test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to next oldest version', async () => {
+ let contents = await fs.readFile(frontmatter2, 'utf8')
contents = processFrontmatter(contents, frontmatter2)
const $ = cheerio.load(contents)
expect($.text().includes('enterprise-server: \'*\'')).toBe(true)
@@ -157,8 +157,8 @@ describe('updating frontmatter', () => {
})
describe('whitespace', () => {
- test('does not add newlines when whitespace control is used', () => {
- let contents = fs.readFileSync(whitespace, 'utf8')
+ test('does not add newlines when whitespace control is used', async () => {
+ let contents = await fs.readFile(whitespace, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text()).toBe('\n Alpha\n')
@@ -167,8 +167,8 @@ describe('whitespace', () => {
expect($('.example4').text()).toBe('\n Alpha\n')
})
- test('does not add newlines when no newlines are present', () => {
- let contents = fs.readFileSync(whitespace, 'utf8')
+ test('does not add newlines when no newlines are present', async () => {
+ let contents = await fs.readFile(whitespace, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example5').text()).toBe('\n Alpha\n')
diff --git a/tests/content/site-data-references.js b/tests/content/site-data-references.js
index c6f0a019bd56..045e33843ba4 100644
--- a/tests/content/site-data-references.js
+++ b/tests/content/site-data-references.js
@@ -3,10 +3,12 @@ const loadSiteData = require('../../lib/site-data')
const { loadPages } = require('../../lib/pages')
const getDataReferences = require('../../lib/get-liquid-data-references')
const frontmatter = require('@github-docs/frontmatter')
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
describe('data references', () => {
+ jest.setTimeout(60 * 1000)
+
let data, pages
beforeAll(async (done) => {
@@ -33,34 +35,34 @@ describe('data references', () => {
expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0)
})
- test('every data reference found in metadata of English content files is defined and has a value', () => {
+ test('every data reference found in metadata of English content files is defined and has a value', async () => {
let errors = []
expect(pages.length).toBeGreaterThan(0)
- pages.forEach(page => {
+ await Promise.all(pages.map(async page => {
const metadataFile = path.join('content', page.relativePath)
- const fileContents = fs.readFileSync(path.join(__dirname, '../..', metadataFile))
+ const fileContents = await fs.readFile(path.join(__dirname, '../..', metadataFile))
const { data: metadata } = frontmatter(fileContents, { filepath: page.fullPath })
const metadataRefs = getDataReferences(JSON.stringify(metadata))
metadataRefs.forEach(key => {
const value = get(data.en, key)
if (typeof value !== 'string') errors.push({ key, value, metadataFile })
})
- })
+ }))
errors = uniqWith(errors, isEqual) // remove duplicates
expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0)
})
- test('every data reference found in English reusable files is defined and has a value', () => {
+ test('every data reference found in English reusable files is defined and has a value', async () => {
let errors = []
const allReusables = data.en.site.data.reusables
const reusables = Object.values(allReusables)
expect(reusables.length).toBeGreaterThan(0)
- reusables.forEach(reusablesPerFile => {
+ await Promise.all(reusables.map(async reusablesPerFile => {
let reusableFile = path.join(__dirname, '../../data/reusables/', getFilenameByValue(allReusables, reusablesPerFile))
- reusableFile = getFilepath(reusableFile)
+ reusableFile = await getFilepath(reusableFile)
const reusableRefs = getDataReferences(JSON.stringify(reusablesPerFile))
@@ -68,21 +70,21 @@ describe('data references', () => {
const value = get(data.en, key)
if (typeof value !== 'string') errors.push({ key, value, reusableFile })
})
- })
+ }))
errors = uniqWith(errors, isEqual) // remove duplicates
expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0)
})
- test('every data reference found in English variable files is defined and has a value', () => {
+ test('every data reference found in English variable files is defined and has a value', async () => {
let errors = []
const allVariables = data.en.site.data.variables
const variables = Object.values(allVariables)
expect(variables.length).toBeGreaterThan(0)
- variables.forEach(variablesPerFile => {
+ await Promise.all(variables.map(async variablesPerFile => {
let variableFile = path.join(__dirname, '../../data/variables/', getFilenameByValue(allVariables, variablesPerFile))
- variableFile = getFilepath(variableFile)
+ variableFile = await getFilepath(variableFile)
const variableRefs = getDataReferences(JSON.stringify(variablesPerFile))
@@ -90,7 +92,7 @@ describe('data references', () => {
const value = get(data.en, key)
if (typeof value !== 'string') errors.push({ key, value, variableFile })
})
- })
+ }))
errors = uniqWith(errors, isEqual) // remove duplicates
expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0)
@@ -102,10 +104,13 @@ function getFilenameByValue (object, value) {
}
// if path exists, assume it's a directory; otherwise, assume a YML extension
-function getFilepath (filepath) {
- filepath = fs.existsSync(filepath)
- ? filepath + '/'
- : filepath + '.yml'
+async function getFilepath (filepath) {
+ try {
+ await fs.stat(filepath)
+ filepath = filepath + '/'
+ } catch (_) {
+ filepath = filepath + '.yml'
+ }
// we only need the relative path
return filepath.replace(path.join(__dirname, '../../'), '')
diff --git a/tests/content/site-data.js b/tests/content/site-data.js
index e563df27d3a9..adbdaa7596eb 100644
--- a/tests/content/site-data.js
+++ b/tests/content/site-data.js
@@ -45,11 +45,11 @@ describe('siteData module (English)', () => {
// TODO: re-enable once Janky flakyness is resolved
test.skip('backfills missing translated site data with English values', async () => {
const newFile = path.join(__dirname, '../../data/newfile.yml')
- fs.writeFileSync(newFile, 'newvalue: bar')
+ await fs.writeFile(newFile, 'newvalue: bar')
const data = await loadSiteData()
expect(get(data, 'en.site.data.newfile.newvalue')).toEqual('bar')
expect(get(data, 'ja.site.data.newfile.newvalue')).toEqual('bar')
- fs.unlinkSync(newFile)
+ await fs.unlink(newFile)
})
test('all Liquid templating is valid', async () => {
diff --git a/tests/graphql/build-changelog-test.js b/tests/graphql/build-changelog-test.js
index 1a55d59bab9c..4620d4aeee67 100644
--- a/tests/graphql/build-changelog-test.js
+++ b/tests/graphql/build-changelog-test.js
@@ -1,6 +1,6 @@
const yaml = require('js-yaml')
const { createChangelogEntry, cleanPreviewTitle, previewAnchor, prependDatedEntry } = require('../../script/graphql/build-changelog')
-const fs = require('fs')
+const fs = require('fs').promises
const MockDate = require('mockdate')
const expectedChangelogEntry = require('../fixtures/changelog-entry')
const expectedUpdatedChangelogFile = require('../fixtures/updated-changelog-file')
@@ -111,18 +111,18 @@ describe('updating the changelog file', () => {
MockDate.reset()
})
- it('modifies the entry object and the file on disk', () => {
+ it('modifies the entry object and the file on disk', async () => {
const testTargetPath = 'tests/graphql/example_changelog.json'
- const previousContents = fs.readFileSync(testTargetPath)
+ const previousContents = await fs.readFile(testTargetPath)
const exampleEntry = { someStuff: true }
const expectedDate = '2020-11-20'
MockDate.set(expectedDate)
prependDatedEntry(exampleEntry, testTargetPath)
- const newContents = fs.readFileSync(testTargetPath, 'utf8')
+ const newContents = await fs.readFile(testTargetPath, 'utf8')
// reset the file:
- fs.writeFileSync(testTargetPath, previousContents)
+ await fs.writeFile(testTargetPath, previousContents)
expect(exampleEntry).toEqual({ someStuff: true, date: expectedDate })
expect(JSON.parse(newContents)).toEqual(expectedUpdatedChangelogFile)
diff --git a/tests/meta/orphan-tests.js b/tests/meta/orphan-tests.js
index 770b10389cfd..9d561140c6fc 100644
--- a/tests/meta/orphan-tests.js
+++ b/tests/meta/orphan-tests.js
@@ -1,20 +1,28 @@
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
+const { filter: asyncFilter } = require('async')
describe('check for orphan tests', () => {
- test('all tests are in sub-directories', () => {
+ test('all tests are in sub-directories', async () => {
// A known list of exceptions that can live outside of directories
const EXCEPTIONS = ['README.md']
const pathToTests = path.join(process.cwd(), 'tests')
// Get a list of files/directories in `/tests`
- const testDirectory = fs.readdirSync(pathToTests)
+ const testDirectory = await fs.readdir(pathToTests)
- const filteredList = testDirectory
+ let filteredList = testDirectory
// Filter out our exceptions
.filter(item => !EXCEPTIONS.includes(item))
- // Don't include directories
- .filter(item => !fs.statSync(path.join(pathToTests, item)).isDirectory())
+ // Don't include directories
+ filteredList = await asyncFilter(
+ filteredList,
+ async item => !(
+ await fs.stat(
+ path.join(pathToTests, item)
+ )
+ ).isDirectory()
+ )
expect(filteredList).toHaveLength(0)
})
diff --git a/tests/rendering/rest.js b/tests/rendering/rest.js
index d26e1b74ad40..34a9428a045b 100644
--- a/tests/rendering/rest.js
+++ b/tests/rendering/rest.js
@@ -1,4 +1,4 @@
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
const { difference, isPlainObject } = require('lodash')
const { getJSON } = require('../helpers/supertest')
@@ -17,7 +17,7 @@ describe('REST references docs', () => {
test('markdown file exists for every operationId prefix in the api.github.com schema', async () => {
const { categories } = require('../../lib/rest')
const referenceDir = path.join(__dirname, '../../content/rest/reference')
- const filenames = fs.readdirSync(referenceDir)
+ const filenames = (await fs.readdir(referenceDir))
.filter(filename => !excludeFromResourceNameCheck.find(excludedFile => filename.endsWith(excludedFile)))
.map(filename => filename.replace('.md', ''))
diff --git a/tests/routing/redirects.js b/tests/routing/redirects.js
index 740cd67d55d0..b41a0888a8c1 100644
--- a/tests/routing/redirects.js
+++ b/tests/routing/redirects.js
@@ -17,8 +17,8 @@ describe('redirects', () => {
done()
})
- test('page.redirects is an array', () => {
- const page = new Page({
+ test('page.redirects is an array', async () => {
+ const page = await Page.init({
relativePath: 'github/collaborating-with-issues-and-pull-requests/about-branches.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -26,8 +26,8 @@ describe('redirects', () => {
expect(isPlainObject(page.redirects)).toBe(true)
})
- test('dotcom homepage page.redirects', () => {
- const page = new Page({
+ test('dotcom homepage page.redirects', async () => {
+ const page = await Page.init({
relativePath: 'github/index.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -41,7 +41,7 @@ describe('redirects', () => {
})
test('converts single `redirect_from` strings values into arrays', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'github/collaborating-with-issues-and-pull-requests/about-conversations-on-github.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
diff --git a/tests/unit/early-access.js b/tests/unit/early-access.js
index f8ad0b3b88fd..80aa48373f95 100644
--- a/tests/unit/early-access.js
+++ b/tests/unit/early-access.js
@@ -1,4 +1,4 @@
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
const { GITHUB_ACTIONS, GITHUB_REPOSITORY } = process.env
@@ -7,17 +7,17 @@ const testViaActionsOnly = runningActionsOnInternalRepo ? test : test.skip
describe('cloning early-access', () => {
testViaActionsOnly('the content directory exists', async () => {
- const eaContentDir = path.join(process.cwd(), 'content/early-access')
- expect(fs.existsSync(eaContentDir)).toBe(true)
+ const eaDir = path.join(process.cwd(), 'content/early-access')
+ expect(await fs.stat(eaDir)).toBeTruthy()
})
testViaActionsOnly('the data directory exists', async () => {
- const eaContentDir = path.join(process.cwd(), 'data/early-access')
- expect(fs.existsSync(eaContentDir)).toBe(true)
+ const eaDir = path.join(process.cwd(), 'data/early-access')
+ expect(await fs.stat(eaDir)).toBeTruthy()
})
testViaActionsOnly('the assets/images directory exists', async () => {
- const eaContentDir = path.join(process.cwd(), 'assets/images/early-access')
- expect(fs.existsSync(eaContentDir)).toBe(true)
+ const eaDir = path.join(process.cwd(), 'assets/images/early-access')
+ expect(await fs.stat(eaDir)).toBeTruthy()
})
})
diff --git a/tests/unit/find-page.js b/tests/unit/find-page.js
index bb422df1b3e5..5772db5f010d 100644
--- a/tests/unit/find-page.js
+++ b/tests/unit/find-page.js
@@ -8,7 +8,7 @@ describe('find page', () => {
jest.setTimeout(1000 * 1000)
test('falls back to the English page if it can\'t find a localized page', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'page-that-does-not-exist-in-translations-dir.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
@@ -24,7 +24,7 @@ describe('find page', () => {
})
test('follows redirects', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'page-with-redirects.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
diff --git a/tests/unit/liquid-helpers.js b/tests/unit/liquid-helpers.js
index ee6b8d3ecf17..41c54a2e3d27 100644
--- a/tests/unit/liquid-helpers.js
+++ b/tests/unit/liquid-helpers.js
@@ -5,6 +5,8 @@ const { set } = require('lodash')
const nonEnterpriseDefaultVersion = require('../../lib/non-enterprise-default-version')
describe('liquid helper tags', () => {
+ jest.setTimeout(60 * 1000)
+
const context = {}
let pageMap
beforeAll(async (done) => {
diff --git a/tests/unit/page.js b/tests/unit/page.js
index 5d1b46a0c3ad..44f98c94a567 100644
--- a/tests/unit/page.js
+++ b/tests/unit/page.js
@@ -15,14 +15,14 @@ const opts = {
}
describe('Page class', () => {
- test('preserves file path info', () => {
- const page = new Page(opts)
+ test('preserves file path info', async () => {
+ const page = await Page.init(opts)
expect(page.relativePath).toBe('github/collaborating-with-issues-and-pull-requests/about-branches.md')
expect(page.fullPath.includes(page.relativePath)).toBe(true)
})
- test('does not error out on translated TOC with no links', () => {
- const page = new Page({
+ test('does not error out on translated TOC with no links', async () => {
+ const page = await Page.init({
relativePath: 'translated-toc-with-no-links-index.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'ja'
@@ -31,30 +31,34 @@ describe('Page class', () => {
})
describe('showMiniToc page property', () => {
- const article = new Page({
- relativePath: 'sample-article.md',
- basePath: path.join(__dirname, '../fixtures'),
- languageCode: 'en'
- })
+ let article, articleWithFM, tocPage, mapTopic
- const articleWithFM = new Page({
- showMiniToc: false,
- relativePath: article.relativePath,
- basePath: article.basePath,
- languageCode: article.languageCode
- })
+ beforeAll(async () => {
+ article = await Page.init({
+ relativePath: 'sample-article.md',
+ basePath: path.join(__dirname, '../fixtures'),
+ languageCode: 'en'
+ })
- const tocPage = new Page({
- relativePath: 'sample-toc-index.md',
- basePath: path.join(__dirname, '../fixtures'),
- languageCode: 'en'
- })
+ articleWithFM = await Page.init({
+ showMiniToc: false,
+ relativePath: article.relativePath,
+ basePath: article.basePath,
+ languageCode: article.languageCode
+ })
+
+ tocPage = await Page.init({
+ relativePath: 'sample-toc-index.md',
+ basePath: path.join(__dirname, '../fixtures'),
+ languageCode: 'en'
+ })
- const mapTopic = new Page({
- mapTopic: true,
- relativePath: article.relativePath,
- basePath: article.basePath,
- languageCode: article.languageCode
+ mapTopic = await Page.init({
+ mapTopic: true,
+ relativePath: article.relativePath,
+ basePath: article.basePath,
+ languageCode: article.languageCode
+ })
})
test('is true by default on articles', () => {
@@ -76,7 +80,7 @@ describe('Page class', () => {
describe('page.render(context)', () => {
test('rewrites links to include the current language prefix and version', async () => {
- const page = new Page(opts)
+ const page = await Page.init(opts)
const context = {
page: { version: nonEnterpriseDefaultVersion },
currentVersion: nonEnterpriseDefaultVersion,
@@ -99,7 +103,7 @@ describe('Page class', () => {
})
test('rewrites links in the intro to include the current language prefix and version', async () => {
- const page = new Page(opts)
+ const page = await Page.init(opts)
page.rawIntro = '[Pull requests](/articles/about-pull-requests)'
const context = {
page: { version: nonEnterpriseDefaultVersion },
@@ -114,7 +118,7 @@ describe('Page class', () => {
})
test('does not rewrite links that include deprecated enterprise release numbers', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'admin/enterprise-management/migrating-from-github-enterprise-1110x-to-2123.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -133,7 +137,7 @@ describe('Page class', () => {
})
test('does not rewrite links to external redirects', async () => {
- const page = new Page(opts)
+ const page = await Page.init(opts)
page.markdown = `${page.markdown}\n\nSee [Capistrano](/capistrano).`
const context = {
page: { version: nonEnterpriseDefaultVersion },
@@ -150,7 +154,7 @@ describe('Page class', () => {
// But they don't have access to our currently supported versions, which we're testing here.
// This test ensures that this works as expected: {% if enterpriseServerVersions contains currentVersion %}
test('renders the expected Enterprise Server versioned content', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'page-versioned-for-all-enterprise-releases.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
@@ -184,27 +188,27 @@ describe('Page class', () => {
})
})
- test('preserves `languageCode`', () => {
- const page = new Page(opts)
+ test('preserves `languageCode`', async () => {
+ const page = await Page.init(opts)
expect(page.languageCode).toBe('en')
})
- test('parentProductId getter', () => {
- let page = new Page({
+ test('parentProductId getter', async () => {
+ let page = await Page.init({
relativePath: 'github/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'en'
})
expect(page.parentProductId).toBe('github')
- page = new Page({
+ page = await Page.init({
relativePath: 'actions/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'en'
})
expect(page.parentProductId).toBe('actions')
- page = new Page({
+ page = await Page.init({
relativePath: 'admin/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'en'
@@ -213,26 +217,26 @@ describe('Page class', () => {
})
describe('permalinks', () => {
- test('is an array', () => {
- const page = new Page(opts)
+ test('is an array', async () => {
+ const page = await Page.init(opts)
expect(Array.isArray(page.permalinks)).toBe(true)
})
- test('has a key for every supported enterprise version (and no deprecated versions)', () => {
- const page = new Page(opts)
+ test('has a key for every supported enterprise version (and no deprecated versions)', async () => {
+ const page = await Page.init(opts)
const pageVersions = page.permalinks.map(permalink => permalink.pageVersion)
expect(enterpriseServerReleases.supported.every(version => pageVersions.includes(`enterprise-server@${version}`))).toBe(true)
expect(enterpriseServerReleases.deprecated.every(version => !pageVersions.includes(`enterprise-server@${version}`))).toBe(true)
})
- test('sets versioned values', () => {
- const page = new Page(opts)
+ test('sets versioned values', async () => {
+ const page = await Page.init(opts)
expect(page.permalinks.find(permalink => permalink.pageVersion === nonEnterpriseDefaultVersion).href).toBe(`/en/${nonEnterpriseDefaultVersion}/github/collaborating-with-issues-and-pull-requests/about-branches`)
expect(page.permalinks.find(permalink => permalink.pageVersion === `enterprise-server@${enterpriseServerReleases.oldestSupported}`).href).toBe(`/en/enterprise-server@${enterpriseServerReleases.oldestSupported}/github/collaborating-with-issues-and-pull-requests/about-branches`)
})
- test('homepage permalinks', () => {
- const page = new Page({
+ test('homepage permalinks', async () => {
+ const page = await Page.init({
relativePath: 'index.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -242,8 +246,8 @@ describe('Page class', () => {
expect(page.permalinks.find(permalink => permalink.pageVersion === 'homepage').href).toBe('/en')
})
- test('permalinks for dotcom-only pages', () => {
- const page = new Page({
+ test('permalinks for dotcom-only pages', async () => {
+ const page = await Page.init({
relativePath: 'github/getting-started-with-github/signing-up-for-a-new-github-account.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -252,8 +256,8 @@ describe('Page class', () => {
expect(page.permalinks.length).toBe(1)
})
- test('permalinks for enterprise-only pages', () => {
- const page = new Page({
+ test('permalinks for enterprise-only pages', async () => {
+ const page = await Page.init({
relativePath: 'products/admin/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
@@ -264,8 +268,8 @@ describe('Page class', () => {
expect(pageVersions.includes(nonEnterpriseDefaultVersion)).toBe(false)
})
- test('permalinks for non-GitHub.com products without Enterprise versions', () => {
- const page = new Page({
+ test('permalinks for non-GitHub.com products without Enterprise versions', async () => {
+ const page = await Page.init({
relativePath: 'products/actions/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
@@ -274,8 +278,8 @@ describe('Page class', () => {
expect(page.permalinks.length).toBe(1)
})
- test('permalinks for non-GitHub.com products with Enterprise versions', () => {
- const page = new Page({
+ test('permalinks for non-GitHub.com products with Enterprise versions', async () => {
+ const page = await Page.init({
relativePath: '/insights/installing-and-configuring-github-insights/about-github-insights.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -318,7 +322,7 @@ describe('Page class', () => {
})
test('fixes translated frontmatter that includes verdadero', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'article-with-mislocalized-frontmatter.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'ja'
@@ -333,7 +337,7 @@ describe('Page class', () => {
// Note this test will go out of date when we deprecate 2.20
test('pages that apply to newer enterprise versions', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'github/administering-a-repository/comparing-releases.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -343,7 +347,7 @@ describe('Page class', () => {
})
test('index page', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'index.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -352,7 +356,7 @@ describe('Page class', () => {
})
test('enterprise admin index page', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'admin/index.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -366,50 +370,50 @@ describe('Page class', () => {
describe('catches errors thrown in Page class', () => {
test('frontmatter parsing error', () => {
- function getPage () {
- return new Page({
+ async function getPage () {
+ return await Page.init({
relativePath: 'page-with-frontmatter-error.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
})
}
- expect(getPage).toThrowError('invalid frontmatter entry')
+ expect(getPage).rejects.toThrowError('invalid frontmatter entry')
})
test('missing versions frontmatter', () => {
- function getPage () {
- return new Page({
+ async function getPage () {
+ return await Page.init({
relativePath: 'page-with-missing-product-versions.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
})
}
- expect(getPage).toThrowError('versions')
+ expect(getPage).rejects.toThrowError('versions')
})
test('English page with a version in frontmatter that its parent product is not available in', () => {
- function getPage () {
- return new Page({
+ async function getPage () {
+ return await Page.init({
relativePath: 'admin/some-category/some-article-with-mismatched-versions-frontmatter.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'en'
})
}
- expect(getPage).toThrowError(/`versions` frontmatter.*? product is not available in/)
+ expect(getPage).rejects.toThrowError(/`versions` frontmatter.*? product is not available in/)
})
test('non-English page with a version in frontmatter that its parent product is not available in', () => {
- function getPage () {
- return new Page({
+ async function getPage () {
+ return await Page.init({
relativePath: 'admin/some-category/some-article-with-mismatched-versions-frontmatter.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'es'
})
}
- expect(getPage).toThrowError(/`versions` frontmatter.*? product is not available in/)
+ expect(getPage).rejects.toThrowError(/`versions` frontmatter.*? product is not available in/)
})
})
diff --git a/tests/unit/pages.js b/tests/unit/pages.js
index f27b73ff1be2..bb405b5e9c61 100644
--- a/tests/unit/pages.js
+++ b/tests/unit/pages.js
@@ -10,6 +10,8 @@ const entities = new Entities()
const { chain, difference } = require('lodash')
describe('pages module', () => {
+ jest.setTimeout(60 * 1000)
+
let pages
beforeAll(async (done) => {
+
Product
-
{% if page.product_video %}
@@ -40,7 +54,7 @@ {{ page.shortTitle }}
++ {{ page.shortTitle }} + + {% if page.beta_product %} + Beta + {% endif %} +
{{ page.intro }}
{% data ui.product_landing.quick_start %}
-
- {% data ui.product_landing.reference_guides %}
-
+ {% if page.introLinks.reference %}
+
+ {% data ui.product_landing.reference_guides %}
+
+ {% endif %}
+
+ {% if page.introLinks.overview %}
+
+ {% data ui.product_landing.overview %}
+
+ {% endif %}
{{ page.shortTitle }}
-
+
{{ link.title }}
+
{% data ui.toc.guides %}
View all {% octicon "arrow-right" height="14" class="v-align-middle" %} @@ -57,7 +71,7 @@{{ link.title }}
+
{% data ui.toc.popular_articles %}
@@ -72,25 +86,27 @@ {{ link.title }}
-
-
- {% data ui.toc.whats_new %}
- View all {% octicon "arrow-right" height="14" class="v-align-middle" %}
+ {% if page.changelog %}
+
+
+ {% data ui.toc.whats_new %}
+ View all {% octicon "arrow-right" height="14" class="v-align-middle" %}
+
+
+ {% for link in page.changelog %}
+ -
+
+
{{ link.title }} →
+
+
+
+ {% endfor %}
+
-
- {% for link in page.changelog %}
- -
-
-
{{ link.title }} →
-
-
-
- {% endfor %}
-
-
+ {% endif %}
{{ renderedPage }}
diff --git a/lib/frontmatter.js b/lib/frontmatter.js
index 9e9e3a0438e0..fa668f48a8ca 100644
--- a/lib/frontmatter.js
+++ b/lib/frontmatter.js
@@ -57,7 +57,8 @@ const schema = {
type: 'object',
properties: {
quickstart: { type: 'string' },
- reference: { type: 'string' }
+ reference: { type: 'string' },
+ overview: { type: 'string' }
}
},
authors: {
@@ -88,6 +89,10 @@ const schema = {
}
}
},
+ // Used in `product-landing.html`
+ beta_product: {
+ type: 'boolean'
+ },
// Show in `product-landing.html`
product_video: {
type: 'string',
diff --git a/lib/page.js b/lib/page.js
index c282f1792fd1..f9274f0119e8 100644
--- a/lib/page.js
+++ b/lib/page.js
@@ -1,5 +1,5 @@
const assert = require('assert')
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
const cheerio = require('cheerio')
const patterns = require('./patterns')
@@ -23,15 +23,30 @@ const slash = require('slash')
const statsd = require('./statsd')
class Page {
- constructor (opts) {
+ static async init (opts) {
assert(opts.relativePath, 'relativePath is required')
assert(opts.basePath, 'basePath is required')
+
+ const relativePath = slash(opts.relativePath)
+ const fullPath = slash(path.join(opts.basePath, relativePath))
+ const raw = await fs.readFile(fullPath, 'utf8')
+
+ return new Page({ ...opts, relativePath, fullPath, raw })
+ }
+
+ static async exists (path) {
+ try {
+ return await fs.stat(path)
+ } catch (err) {
+ if (err.code === 'ENOENT') return false
+ console.error(err)
+ }
+ }
+
+ constructor (opts) {
assert(opts.languageCode, 'languageCode is required')
Object.assign(this, { ...opts })
- this.relativePath = slash(this.relativePath)
- this.fullPath = slash(path.join(this.basePath, this.relativePath))
- this.raw = fs.readFileSync(this.fullPath, 'utf8')
// TODO remove this when crowdin-support issue 66 has been resolved
if (this.languageCode !== 'en' && this.raw.includes(': verdadero')) {
diff --git a/lib/pages.js b/lib/pages.js
index cdca1fae1e2a..4db70e7dd5cb 100644
--- a/lib/pages.js
+++ b/lib/pages.js
@@ -2,42 +2,50 @@ const path = require('path')
const walk = require('walk-sync').entries
const Page = require('./page')
const languages = require('./languages')
-const fs = require('fs')
+const { mapLimit, filterLimit } = require('async')
+const FILE_READ_LIMIT = 500
async function loadPageList () {
const pageList = []
// load english pages
const englishPath = path.join(__dirname, '..', languages.en.dir, 'content')
- const englishPages = walk(englishPath)
- .filter(({ relativePath }) => {
- return relativePath.endsWith('.md') &&
- !relativePath.includes('README')
- })
- .map(fileData => new Page({ ...fileData, languageCode: languages.en.code }))
-
+ const englishPaths = walk(englishPath)
+ .filter(({ relativePath }) =>
+ relativePath.endsWith('.md') && !relativePath.includes('README')
+ )
+ const englishPages = await mapLimit(
+ englishPaths,
+ FILE_READ_LIMIT,
+ async fileData => await Page.init({ ...fileData, languageCode: languages.en.code })
+ )
pageList.push(...englishPages)
// load matching pages in other languages
- for (const page of englishPages) {
- for (const language of Object.values(languages)) {
- if (language.code === 'en') continue
-
+ let localizedPaths = Object.values(languages)
+ .filter(({ code }) => code !== 'en')
+ .map(language => {
const basePath = path.join(__dirname, '..', language.dir, 'content')
- const localizedPath = path.join(basePath, page.relativePath)
- try {
- fs.statSync(localizedPath)
- } catch (_) {
- continue
- }
-
- pageList.push(new Page({
- relativePath: page.relativePath,
+ return englishPages.map(page => ({
basePath,
+ relativePath: page.relativePath,
+ localizedPath: path.join(basePath, page.relativePath),
languageCode: language.code
}))
- }
- }
+ })
+ .flat()
+ localizedPaths = await filterLimit(
+ localizedPaths,
+ FILE_READ_LIMIT,
+ async ({ localizedPath }) => Page.exists(localizedPath)
+ )
+ const localizedPages = await mapLimit(
+ localizedPaths,
+ FILE_READ_LIMIT,
+ async ({ basePath, relativePath, languageCode }) =>
+ await Page.init({ basePath, relativePath, languageCode })
+ )
+ pageList.push(...localizedPages)
return pageList
}
diff --git a/lib/rest/static/decorated/api.github.com.json b/lib/rest/static/decorated/api.github.com.json
index e2f389b736df..f5234c81ccac 100644
--- a/lib/rest/static/decorated/api.github.com.json
+++ b/lib/rest/static/decorated/api.github.com.json
@@ -5975,6 +5975,123 @@
"bodyParameters": [],
"descriptionHTML": "Forces the removal of a self-hosted runner from an enterprise. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.
\nYou must authenticate using an access token with the admin:enterprise scope to use this endpoint.
"
},
+ {
+ "verb": "get",
+ "requestPath": "/enterprises/{enterprise}/audit-log",
+ "serverUrl": "https://api.github.com",
+ "parameters": [
+ {
+ "name": "enterprise",
+ "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.
"
+ },
+ {
+ "name": "phrase",
+ "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A search phrase. For more information, see Searching the audit log.
"
+ },
+ {
+ "name": "include",
+ "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "enum": [
+ "web",
+ "git",
+ "all"
+ ]
+ },
+ "descriptionHTML": "The event types to include:
\n\nweb - returns web (non-Git) eventsgit - returns Git eventsall - returns both web and Git events
\nThe default is web.
"
+ },
+ {
+ "name": "after",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.
"
+ },
+ {
+ "name": "before",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.
"
+ },
+ {
+ "name": "per_page",
+ "description": "Results per page (max 100)",
+ "in": "query",
+ "schema": {
+ "type": "integer",
+ "default": 30
+ },
+ "descriptionHTML": "Results per page (max 100)
"
+ }
+ ],
+ "x-codeSamples": [
+ {
+ "lang": "Shell",
+ "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/enterprises/ENTERPRISE/audit-log",
+ "html": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/enterprises/ENTERPRISE/audit-log
"
+ },
+ {
+ "lang": "JavaScript",
+ "source": "await octokit.request('GET /enterprises/{enterprise}/audit-log', {\n enterprise: 'enterprise'\n})",
+ "html": "await octokit.request('GET /enterprises/{enterprise}/audit-log', {\n enterprise: 'enterprise'\n})\n
"
+ }
+ ],
+ "summary": "Get the audit log for an enterprise",
+ "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the `admin:enterprise` scope.",
+ "operationId": "audit-log/get-audit-log",
+ "tags": [
+ "audit-log"
+ ],
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/enterprise-admin#get-the-audit-log-for-an-enterprise"
+ },
+ "x-github": {
+ "githubCloudOnly": true,
+ "enabledForGitHubApps": false,
+ "previews": [],
+ "category": "enterprise-admin",
+ "subcategory": "audit-log"
+ },
+ "slug": "get-the-audit-log-for-an-enterprise",
+ "category": "enterprise-admin",
+ "categoryLabel": "Enterprise admin",
+ "subcategory": "audit-log",
+ "subcategoryLabel": "Audit log",
+ "notes": [],
+ "bodyParameters": [],
+ "descriptionHTML": "Note: The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.
\nGets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the admin:enterprise scope.
",
+ "responses": [
+ {
+ "httpStatusCode": "200",
+ "httpStatusMessage": "OK",
+ "description": "Default response",
+ "payload": "[\n {\n \"@timestamp\": 1606929874512,\n \"action\": \"team.add_member\",\n \"actor\": \"octocat\",\n \"created_at\": 1606929874512,\n \"org\": \"octo-corp\",\n \"team\": \"octo-corp/example-team\",\n \"user\": \"monalisa\"\n },\n {\n \"@timestamp\": 1606507117008,\n \"action\": \"org.create\",\n \"actor\": \"octocat\",\n \"created_at\": 1606507117008,\n \"org\": \"octocat-test-org\"\n },\n {\n \"@timestamp\": 1605719148837,\n \"action\": \"repo.destroy\",\n \"actor\": \"monalisa\",\n \"created_at\": 1605719148837,\n \"org\": \"mona-org\",\n \"repo\": \"mona-org/mona-test-repo\",\n \"visibility\": \"private\"\n }\n]\n
"
+ }
+ ]
+ },
{
"verb": "get",
"requestPath": "/enterprises/{enterprise}/settings/billing/actions",
@@ -14225,6 +14342,120 @@
"bodyParameters": [],
"descriptionHTML": "Removes a repository from an organization secret when the visibility for repository access is set to selected. The visibility is set when you Create or update an organization secret. You must authenticate using an access token with the admin:org scope to use this endpoint. GitHub Apps must have the secrets organization permission to use this endpoint.
"
},
+ {
+ "verb": "get",
+ "requestPath": "/orgs/{org}/audit-log",
+ "serverUrl": "https://api.github.com",
+ "parameters": [
+ {
+ "name": "org",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": ""
+ },
+ {
+ "name": "phrase",
+ "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A search phrase. For more information, see Searching the audit log.
"
+ },
+ {
+ "name": "include",
+ "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "enum": [
+ "web",
+ "git",
+ "all"
+ ]
+ },
+ "descriptionHTML": "The event types to include:
\n\nweb - returns web (non-Git) eventsgit - returns Git eventsall - returns both web and Git events
\nThe default is web.
"
+ },
+ {
+ "name": "after",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.
"
+ },
+ {
+ "name": "before",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "descriptionHTML": "A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.
"
+ },
+ {
+ "name": "per_page",
+ "description": "Results per page (max 100)",
+ "in": "query",
+ "schema": {
+ "type": "integer",
+ "default": 30
+ },
+ "descriptionHTML": "Results per page (max 100)
"
+ }
+ ],
+ "x-codeSamples": [
+ {
+ "lang": "Shell",
+ "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/orgs/ORG/audit-log",
+ "html": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/orgs/ORG/audit-log
"
+ },
+ {
+ "lang": "JavaScript",
+ "source": "await octokit.request('GET /orgs/{org}/audit-log', {\n org: 'org'\n})",
+ "html": "await octokit.request('GET /orgs/{org}/audit-log', {\n org: 'org'\n})\n
"
+ }
+ ],
+ "summary": "Get the audit log for an organization",
+ "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an organization. For more information, see \"[Reviewing the audit log for your organization](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization).\"\n\nTo use this endpoint, you must be an organization owner, and you must use an access token with the `admin:org` scope. GitHub Apps must have the `organization_administration` read permission to use this endpoint.",
+ "operationId": "orgs/get-audit-log",
+ "tags": [
+ "orgs"
+ ],
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/orgs#get-the-audit-log-for-an-organization"
+ },
+ "x-github": {
+ "githubCloudOnly": true,
+ "enabledForGitHubApps": true,
+ "previews": [],
+ "category": "orgs",
+ "subcategory": null
+ },
+ "slug": "get-the-audit-log-for-an-organization",
+ "category": "orgs",
+ "categoryLabel": "Orgs",
+ "notes": [],
+ "bodyParameters": [],
+ "descriptionHTML": "Note: The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.
\nGets the audit log for an organization. For more information, see \"Reviewing the audit log for your organization.\"
\nTo use this endpoint, you must be an organization owner, and you must use an access token with the admin:org scope. GitHub Apps must have the organization_administration read permission to use this endpoint.
",
+ "responses": [
+ {
+ "httpStatusCode": "200",
+ "httpStatusMessage": "OK",
+ "description": "Default response",
+ "payload": "[\n {\n \"@timestamp\": 1606929874512,\n \"action\": \"team.add_member\",\n \"actor\": \"octocat\",\n \"created_at\": 1606929874512,\n \"org\": \"octo-corp\",\n \"team\": \"octo-corp/example-team\",\n \"user\": \"monalisa\"\n },\n {\n \"@timestamp\": 1606507117008,\n \"action\": \"org.create\",\n \"actor\": \"octocat\",\n \"created_at\": 1606507117008,\n \"org\": \"octocat-test-org\"\n },\n {\n \"@timestamp\": 1605719148837,\n \"action\": \"repo.destroy\",\n \"actor\": \"monalisa\",\n \"created_at\": 1605719148837,\n \"org\": \"mona-org\",\n \"repo\": \"mona-org/mona-test-repo\",\n \"visibility\": \"private\"\n }\n]\n
"
+ }
+ ]
+ },
{
"verb": "get",
"requestPath": "/orgs/{org}/blocks",
diff --git a/lib/rest/static/dereferenced/api.github.com.deref.json b/lib/rest/static/dereferenced/api.github.com.deref.json
index 873643c5bcd5..7dbc79d26958 100644
--- a/lib/rest/static/dereferenced/api.github.com.deref.json
+++ b/lib/rest/static/dereferenced/api.github.com.deref.json
@@ -17051,6 +17051,254 @@
}
}
},
+ "/enterprises/{enterprise}/audit-log": {
+ "get": {
+ "summary": "Get the audit log for an enterprise",
+ "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the `admin:enterprise` scope.",
+ "operationId": "audit-log/get-audit-log",
+ "tags": [
+ "audit-log"
+ ],
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/enterprise-admin#get-the-audit-log-for-an-enterprise"
+ },
+ "parameters": [
+ {
+ "name": "enterprise",
+ "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "phrase",
+ "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "include",
+ "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "enum": [
+ "web",
+ "git",
+ "all"
+ ]
+ }
+ },
+ {
+ "name": "after",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "before",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "per_page",
+ "description": "Results per page (max 100)",
+ "in": "query",
+ "schema": {
+ "type": "integer",
+ "default": 30
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "@timestamp": {
+ "type": "integer",
+ "description": "The time the audit log event occurred, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)."
+ },
+ "action": {
+ "type": "string",
+ "description": "The name of the action that was performed, for example `user.login` or `repo.create`."
+ },
+ "active": {
+ "type": "boolean"
+ },
+ "active_was": {
+ "type": "boolean"
+ },
+ "actor": {
+ "type": "string",
+ "description": "The actor who performed the action."
+ },
+ "blocked_user": {
+ "type": "string",
+ "description": "The username of the account being blocked."
+ },
+ "business": {
+ "type": "string"
+ },
+ "config": {
+ "type": "array"
+ },
+ "config_was": {
+ "type": "array"
+ },
+ "content_type": {
+ "type": "string"
+ },
+ "created_at": {
+ "type": "integer",
+ "description": "The time the audit log event was recorded, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)."
+ },
+ "deploy_key_fingerprint": {
+ "type": "string"
+ },
+ "emoji": {
+ "type": "string"
+ },
+ "events": {
+ "type": "array"
+ },
+ "events_were": {
+ "type": "array"
+ },
+ "explanation": {
+ "type": "string"
+ },
+ "fingerprint": {
+ "type": "string"
+ },
+ "hook_id": {
+ "type": "integer"
+ },
+ "limited_availability": {
+ "type": "boolean"
+ },
+ "message": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "old_user": {
+ "type": "string"
+ },
+ "openssh_public_key": {
+ "type": "string"
+ },
+ "org": {
+ "type": "string"
+ },
+ "previous_visibility": {
+ "type": "string"
+ },
+ "read_only": {
+ "type": "boolean"
+ },
+ "repo": {
+ "type": "string",
+ "description": "The name of the repository."
+ },
+ "repository": {
+ "type": "string",
+ "description": "The name of the repository."
+ },
+ "repository_public": {
+ "type": "boolean"
+ },
+ "target_login": {
+ "type": "string"
+ },
+ "team": {
+ "type": "string"
+ },
+ "transport_protocol": {
+ "type": "integer",
+ "description": "The type of protocol (for example, HTTP or SSH) used to transfer Git data."
+ },
+ "transport_protocol_name": {
+ "type": "string",
+ "description": "A human readable name for the protocol (for example, HTTP or SSH) used to transfer Git data."
+ },
+ "user": {
+ "type": "string",
+ "description": "The user that was affected by the action performed (if available)."
+ },
+ "visibility": {
+ "type": "string",
+ "description": "The repository visibility, for example `public` or `private`."
+ }
+ }
+ }
+ },
+ "examples": {
+ "default": {
+ "value": [
+ {
+ "@timestamp": 1606929874512,
+ "action": "team.add_member",
+ "actor": "octocat",
+ "created_at": 1606929874512,
+ "org": "octo-corp",
+ "team": "octo-corp/example-team",
+ "user": "monalisa"
+ },
+ {
+ "@timestamp": 1606507117008,
+ "action": "org.create",
+ "actor": "octocat",
+ "created_at": 1606507117008,
+ "org": "octocat-test-org"
+ },
+ {
+ "@timestamp": 1605719148837,
+ "action": "repo.destroy",
+ "actor": "monalisa",
+ "created_at": 1605719148837,
+ "org": "mona-org",
+ "repo": "mona-org/mona-test-repo",
+ "visibility": "private"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "x-github": {
+ "githubCloudOnly": true,
+ "enabledForGitHubApps": false,
+ "previews": [
+
+ ],
+ "category": "enterprise-admin",
+ "subcategory": "audit-log"
+ }
+ }
+ },
"/enterprises/{enterprise}/settings/billing/actions": {
"get": {
"summary": "Get GitHub Actions billing for an enterprise",
@@ -49105,6 +49353,253 @@
}
}
},
+ "/orgs/{org}/audit-log": {
+ "get": {
+ "summary": "Get the audit log for an organization",
+ "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an organization. For more information, see \"[Reviewing the audit log for your organization](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization).\"\n\nTo use this endpoint, you must be an organization owner, and you must use an access token with the `admin:org` scope. GitHub Apps must have the `organization_administration` read permission to use this endpoint.",
+ "operationId": "orgs/get-audit-log",
+ "tags": [
+ "orgs"
+ ],
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/orgs#get-the-audit-log-for-an-organization"
+ },
+ "parameters": [
+ {
+ "name": "org",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "phrase",
+ "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "include",
+ "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "enum": [
+ "web",
+ "git",
+ "all"
+ ]
+ }
+ },
+ {
+ "name": "after",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "before",
+ "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "per_page",
+ "description": "Results per page (max 100)",
+ "in": "query",
+ "schema": {
+ "type": "integer",
+ "default": 30
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "@timestamp": {
+ "type": "integer",
+ "description": "The time the audit log event occurred, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)."
+ },
+ "action": {
+ "type": "string",
+ "description": "The name of the action that was performed, for example `user.login` or `repo.create`."
+ },
+ "active": {
+ "type": "boolean"
+ },
+ "active_was": {
+ "type": "boolean"
+ },
+ "actor": {
+ "type": "string",
+ "description": "The actor who performed the action."
+ },
+ "blocked_user": {
+ "type": "string",
+ "description": "The username of the account being blocked."
+ },
+ "business": {
+ "type": "string"
+ },
+ "config": {
+ "type": "array"
+ },
+ "config_was": {
+ "type": "array"
+ },
+ "content_type": {
+ "type": "string"
+ },
+ "created_at": {
+ "type": "integer",
+ "description": "The time the audit log event was recorded, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)."
+ },
+ "deploy_key_fingerprint": {
+ "type": "string"
+ },
+ "emoji": {
+ "type": "string"
+ },
+ "events": {
+ "type": "array"
+ },
+ "events_were": {
+ "type": "array"
+ },
+ "explanation": {
+ "type": "string"
+ },
+ "fingerprint": {
+ "type": "string"
+ },
+ "hook_id": {
+ "type": "integer"
+ },
+ "limited_availability": {
+ "type": "boolean"
+ },
+ "message": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "old_user": {
+ "type": "string"
+ },
+ "openssh_public_key": {
+ "type": "string"
+ },
+ "org": {
+ "type": "string"
+ },
+ "previous_visibility": {
+ "type": "string"
+ },
+ "read_only": {
+ "type": "boolean"
+ },
+ "repo": {
+ "type": "string",
+ "description": "The name of the repository."
+ },
+ "repository": {
+ "type": "string",
+ "description": "The name of the repository."
+ },
+ "repository_public": {
+ "type": "boolean"
+ },
+ "target_login": {
+ "type": "string"
+ },
+ "team": {
+ "type": "string"
+ },
+ "transport_protocol": {
+ "type": "integer",
+ "description": "The type of protocol (for example, HTTP or SSH) used to transfer Git data."
+ },
+ "transport_protocol_name": {
+ "type": "string",
+ "description": "A human readable name for the protocol (for example, HTTP or SSH) used to transfer Git data."
+ },
+ "user": {
+ "type": "string",
+ "description": "The user that was affected by the action performed (if available)."
+ },
+ "visibility": {
+ "type": "string",
+ "description": "The repository visibility, for example `public` or `private`."
+ }
+ }
+ }
+ },
+ "examples": {
+ "default": {
+ "value": [
+ {
+ "@timestamp": 1606929874512,
+ "action": "team.add_member",
+ "actor": "octocat",
+ "created_at": 1606929874512,
+ "org": "octo-corp",
+ "team": "octo-corp/example-team",
+ "user": "monalisa"
+ },
+ {
+ "@timestamp": 1606507117008,
+ "action": "org.create",
+ "actor": "octocat",
+ "created_at": 1606507117008,
+ "org": "octocat-test-org"
+ },
+ {
+ "@timestamp": 1605719148837,
+ "action": "repo.destroy",
+ "actor": "monalisa",
+ "created_at": 1605719148837,
+ "org": "mona-org",
+ "repo": "mona-org/mona-test-repo",
+ "visibility": "private"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "x-github": {
+ "githubCloudOnly": true,
+ "enabledForGitHubApps": true,
+ "previews": [
+
+ ],
+ "category": "orgs",
+ "subcategory": null
+ }
+ }
+ },
"/orgs/{org}/blocks": {
"get": {
"summary": "List users blocked by an organization",
diff --git a/middleware/categories-for-support-team.js b/middleware/categories-for-support-team.js
index 7a38fb0cdea4..4b550a566efe 100644
--- a/middleware/categories-for-support-team.js
+++ b/middleware/categories-for-support-team.js
@@ -2,7 +2,7 @@
// to quickly search for Help articles by title and insert the link to
// the article into a reply to a customer.
const path = require('path')
-const fs = require('fs')
+const fs = require('fs').promises
const matter = require('gray-matter')
const dotcomDir = path.join(__dirname, '../content/github')
const dotcomIndex = path.join(dotcomDir, 'index.md')
@@ -10,24 +10,22 @@ const linkRegex = /{% (?:topic_)?link_in_list ?\/(.*?) ?%}/g
module.exports = async (req, res, next) => {
if (req.path !== '/categories.json') return next()
- const categories = generateCategories()
+ const categories = await generateCategories()
return res.json(categories)
}
-function generateCategories () {
+async function generateCategories () {
// get links included in dotcom index page.
// each link corresponds to a dotcom subdirectory
// example: getting-started-with-github
- const links = getLinks(fs.readFileSync(dotcomIndex, 'utf8'))
-
- const categories = []
+ const links = getLinks(await fs.readFile(dotcomIndex, 'utf8'))
// get links included in each subdir's index page
// these are links to articles
- links.forEach(link => {
+ const categories = await Promise.all(links.map(async link => {
const category = {}
const indexPath = getPath(link, 'index')
- const indexContents = fs.readFileSync(indexPath, 'utf8')
+ const indexContents = await fs.readFile(indexPath, 'utf8')
const { data, content } = matter(indexContents)
// get name from title frontmatter
@@ -36,29 +34,23 @@ function generateCategories () {
// get child article links
const articleLinks = getLinks(content)
- const publishedArticles = []
-
- articleLinks.forEach(articleLink => {
- const publishedArticle = {}
-
+ category.published_articles = (await Promise.all(articleLinks.map(async articleLink => {
// get title from frontmatter
const articlePath = getPath(link, articleLink)
- const articleContents = fs.readFileSync(articlePath, 'utf8')
+ const articleContents = await fs.readFile(articlePath, 'utf8')
const { data } = matter(articleContents)
// do not include map topics in list of published articles
if (data.mapTopic) return
- publishedArticle.title = data.title
- publishedArticle.slug = articleLink
-
- publishedArticles.push(publishedArticle)
- })
-
- category.published_articles = publishedArticles
+ return {
+ title: data.title,
+ slug: articleLink
+ }
+ }))).filter(Boolean)
- categories.push(category)
- })
+ return category
+ }))
return categories
}
diff --git a/package-lock.json b/package-lock.json
index b33963cf8bda..b0f2a9c3e7e9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -5577,8 +5577,7 @@
"async": {
"version": "3.2.0",
"resolved": "https://registry.npmjs.org/async/-/async-3.2.0.tgz",
- "integrity": "sha512-TR2mEZFVOj2pLStYxLht7TyfuRzaydfpxr3k9RpHIzMgw7A64dzsdqCxH1WJyQdoe8T10nDXd9wnEigmiuHIZw==",
- "dev": true
+ "integrity": "sha512-TR2mEZFVOj2pLStYxLht7TyfuRzaydfpxr3k9RpHIzMgw7A64dzsdqCxH1WJyQdoe8T10nDXd9wnEigmiuHIZw=="
},
"async-each": {
"version": "1.0.3",
diff --git a/package.json b/package.json
index a0663ce8fb91..a0cae4097a62 100644
--- a/package.json
+++ b/package.json
@@ -27,6 +27,7 @@
"@primer/css": "^15.1.0",
"@primer/octicons": "^11.0.0",
"algoliasearch": "^3.35.1",
+ "async": "^3.2.0",
"babel-loader": "^8.1.0",
"babel-preset-env": "^1.7.0",
"browser-date-formatter": "^3.0.3",
@@ -94,7 +95,6 @@
"devDependencies": {
"@actions/core": "^1.2.6",
"ajv": "^6.11.0",
- "async": "^3.2.0",
"await-sleep": "0.0.1",
"aws-sdk": "^2.610.0",
"babel-eslint": "^10.1.0",
diff --git a/script/check-s3-images.js b/script/check-s3-images.js
index 00ef528b7cda..6c83a4dc8a14 100755
--- a/script/check-s3-images.js
+++ b/script/check-s3-images.js
@@ -12,6 +12,7 @@ const patterns = require('../lib/patterns')
const authenticateToAWS = require('../lib/authenticate-to-aws.js')
const readlineSync = require('readline-sync')
const { execSync } = require('child_process')
+const enterpriseServerVersions = Object.keys(allVersions).filter(v => v.startsWith('enterprise-server@'))
const uploadScript = path.join(process.cwd(), 'script/upload-images-to-s3.js')
// ignore the non-enterprise default version
@@ -51,7 +52,8 @@ async function main () {
page,
site: siteData,
currentVersion: version,
- currentLanguage: 'en'
+ currentLanguage: 'en',
+ enterpriseServerVersions
}
const rendered = await renderContent(page.markdown, context)
diff --git a/server.js b/server.js
index 1af6650790b9..744d1fa924c3 100644
--- a/server.js
+++ b/server.js
@@ -16,8 +16,11 @@ if (!module.parent) {
// check that the development server is not already running
portUsed.check(port).then(async status => {
if (status === false) {
- // If in production, warm the server at the start
- if (process.env.NODE_ENV === 'production') warmServer()
+ // If in a deployed environment, warm the server at the start
+ if (process.env.NODE_ENV === 'production') {
+ // If in a production environment, wait for the cache to be fully warmed.
+ await warmServer()
+ }
// workaround for https://github.com/expressjs/express/issues/1101
const server = require('http').createServer(app)
diff --git a/tests/browser/browser.js b/tests/browser/browser.js
index 64fdb083ab33..aca6b864a720 100644
--- a/tests/browser/browser.js
+++ b/tests/browser/browser.js
@@ -3,6 +3,8 @@ const sleep = require('await-sleep')
const querystring = require('querystring')
describe('homepage', () => {
+ jest.setTimeout(60 * 1000)
+
test('should be titled "GitHub Documentation"', async () => {
await page.goto('http://localhost:4001')
await expect(page.title()).resolves.toMatch('GitHub Documentation')
@@ -10,6 +12,8 @@ describe('homepage', () => {
})
describe('algolia browser search', () => {
+ jest.setTimeout(60 * 1000)
+
it('works on the homepage', async () => {
await page.goto('http://localhost:4001/en')
await page.click('#search-input-container input[type="search"]')
diff --git a/tests/content/category-pages.js b/tests/content/category-pages.js
index 702c2d4c8c00..218301846ef1 100644
--- a/tests/content/category-pages.js
+++ b/tests/content/category-pages.js
@@ -42,15 +42,17 @@ describe('category pages', () => {
// Get links included in product index page.
// Each link corresponds to a product subdirectory (category).
// Example: "getting-started-with-github"
- const contents = fs.readFileSync(productIndex, 'utf8')
+ const contents = fs.readFileSync(productIndex, 'utf8') // TODO move to async
const { content } = matter(contents)
+ const productDir = path.dirname(productIndex)
+
const categoryLinks = getLinks(content)
- // HACK: I'm not really sure why this file is a one-off but it is...
- .filter(link => !(productName === 'actions' && link === 'quickstart'))
+ // Only include category directories, not standalone category files like content/actions/quickstart.md
+ .filter(link => fs.existsSync(getPath(productDir, link, 'index')))
+ // TODO this should move to async, but you can't asynchronously define tests with Jest...
// Map those to the Markdown file paths that represent that category page index
- const productDir = path.dirname(productIndex)
const categoryPaths = categoryLinks.map(link => getPath(productDir, link, 'index'))
// Make them relative for nicer display in test names
diff --git a/tests/content/crowdin-config.js b/tests/content/crowdin-config.js
index 63301e09935d..fd26e74b42e7 100644
--- a/tests/content/crowdin-config.js
+++ b/tests/content/crowdin-config.js
@@ -4,6 +4,8 @@ const ignoredPagePaths = config.files[0].ignore
const ignoredDataPaths = config.files[2].ignore
describe('crowdin.yml config file', () => {
+ jest.setTimeout(60 * 1000)
+
let pages
beforeAll(async (done) => {
pages = await loadPages()
diff --git a/tests/content/featured-links.js b/tests/content/featured-links.js
index c5b476153bcb..9829f1abd71a 100644
--- a/tests/content/featured-links.js
+++ b/tests/content/featured-links.js
@@ -45,8 +45,9 @@ describe('featuredLinks', () => {
test('featured links respect versioning', async () => {
const $ = await getDOM(`/en/enterprise/${enterpriseServerReleases.latest}/user/packages`)
- const $featuredLinks = $('.featured-links a')
+ const $featuredLinks = $('.all-articles-list a')
expect($featuredLinks.length).toBeGreaterThan(2)
+ expect($featuredLinks.text().includes('Package client guides for GitHub Packages')).toBe(true)
// does not include dotcom-only links
expect($featuredLinks.text().includes('About GitHub Container Registry')).toBe(false)
expect($featuredLinks.text().includes('Getting started with GitHub Container Registry')).toBe(false)
diff --git a/tests/content/glossary.js b/tests/content/glossary.js
index 3e3aea66f98d..3f278e501647 100644
--- a/tests/content/glossary.js
+++ b/tests/content/glossary.js
@@ -9,7 +9,10 @@ describe('glossaries', () => {
test('are broken into external, internal, and candidates', async () => {
const keys = Object.keys(glossaries)
- expect(keys).toEqual(['candidates', 'external', 'internal'])
+ expect(keys).toHaveLength(3)
+ expect(keys).toContain('candidates')
+ expect(keys).toContain('external')
+ expect(keys).toContain('internal')
})
test('every entry has a valid term', async () => {
diff --git a/tests/content/remove-liquid-statements.js b/tests/content/remove-liquid-statements.js
index 80fd02166945..f94dd5ae5cfa 100644
--- a/tests/content/remove-liquid-statements.js
+++ b/tests/content/remove-liquid-statements.js
@@ -1,4 +1,4 @@
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
const cheerio = require('cheerio')
const matter = require('gray-matter')
@@ -35,8 +35,8 @@ function processFrontmatter (contents, file) {
}
describe('removing liquid statements only', () => {
- test('removes liquid statements that specify "greater than version to deprecate"', () => {
- let contents = fs.readFileSync(greaterThan, 'utf8')
+ test('removes liquid statements that specify "greater than version to deprecate"', async () => {
+ let contents = await fs.readFile(greaterThan, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('Alpha')
@@ -57,8 +57,8 @@ Alpha\n\n{% else %}\n\nBravo\n\n{% if currentVersion ver_gt "enterprise-server@2
expect($('.example10').text().trim()).toBe('Alpha')
})
- test('removes liquid statements that specify "and greater than version to deprecate"', () => {
- let contents = fs.readFileSync(andGreaterThan1, 'utf8')
+ test('removes liquid statements that specify "and greater than version to deprecate"', async () => {
+ let contents = await fs.readFile(andGreaterThan1, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('{% if currentVersion != "free-pro-team@latest" %}\n\nAlpha\n\n{% endif %}')
@@ -71,8 +71,8 @@ Alpha\n\n{% if currentVersion != "free-pro-team@latest" %}\n\nBravo\n\n{% endif
Alpha\n\n{% if currentVersion ver_gt "enterprise-server@2.16" %}\n\nBravo\n\n{% endif %}\n\n{% endif %}`)
})
- test('removes liquid statements that specify "and greater than version to deprecate" (alternate format)', () => {
- let contents = fs.readFileSync(andGreaterThan2, 'utf8')
+ test('removes liquid statements that specify "and greater than version to deprecate" (alternate format)', async () => {
+ let contents = await fs.readFile(andGreaterThan2, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('{% if currentVersion ver_lt "enterprise-server@2.16" %}\n\nAlpha\n\n{% endif %}')
@@ -85,8 +85,8 @@ Alpha\n\n{% if currentVersion ver_lt "enterprise-server@2.16" %}\n\nBravo\n\n{%
Alpha\n\n{% if currentVersion != "free-pro-team@latest" %}\n\nBravo\n\n{% endif %}\n\n{% endif %}`)
})
- test('removes liquid statements that specify "not equals version to deprecate"', () => {
- let contents = fs.readFileSync(notEquals, 'utf8')
+ test('removes liquid statements that specify "not equals version to deprecate"', async () => {
+ let contents = await fs.readFile(notEquals, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('Alpha')
@@ -103,8 +103,8 @@ Alpha\n\n{% endif %}`)
})
describe('removing liquid statements and content', () => {
- test('removes interior content and liquid statements that specify "equals version to deprecate"', () => {
- let contents = fs.readFileSync(equals, 'utf8')
+ test('removes interior content and liquid statements that specify "equals version to deprecate"', async () => {
+ let contents = await fs.readFile(equals, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('')
@@ -117,8 +117,8 @@ Alpha\n\n{% else %}\n\nCharlie\n\n{% endif %}`)
expect($('.example6').text().trim()).toBe('Charlie\n\nBravo')
})
- test('removes interior content and liquid statements that specify "less than next oldest than version to deprecate"', () => {
- let contents = fs.readFileSync(lessThanNextOldest, 'utf8')
+ test('removes interior content and liquid statements that specify "less than next oldest than version to deprecate"', async () => {
+ let contents = await fs.readFile(lessThanNextOldest, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text().trim()).toBe('Alpha')
@@ -137,8 +137,8 @@ Charlie\n\n{% else %}\n\nDelta\n\n{% endif %}\n\nEcho`)
})
describe('updating frontmatter', () => {
- test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to version to deprecate', () => {
- let contents = fs.readFileSync(frontmatter1, 'utf8')
+ test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to version to deprecate', async () => {
+ let contents = await fs.readFile(frontmatter1, 'utf8')
contents = processFrontmatter(contents, frontmatter1)
const $ = cheerio.load(contents)
// console.log('foo')
@@ -147,8 +147,8 @@ describe('updating frontmatter', () => {
expect($.text().includes('enterprise-server: \'>=2.13\'')).toBe(false)
})
- test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to next oldest version', () => {
- let contents = fs.readFileSync(frontmatter2, 'utf8')
+ test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to next oldest version', async () => {
+ let contents = await fs.readFile(frontmatter2, 'utf8')
contents = processFrontmatter(contents, frontmatter2)
const $ = cheerio.load(contents)
expect($.text().includes('enterprise-server: \'*\'')).toBe(true)
@@ -157,8 +157,8 @@ describe('updating frontmatter', () => {
})
describe('whitespace', () => {
- test('does not add newlines when whitespace control is used', () => {
- let contents = fs.readFileSync(whitespace, 'utf8')
+ test('does not add newlines when whitespace control is used', async () => {
+ let contents = await fs.readFile(whitespace, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example1').text()).toBe('\n Alpha\n')
@@ -167,8 +167,8 @@ describe('whitespace', () => {
expect($('.example4').text()).toBe('\n Alpha\n')
})
- test('does not add newlines when no newlines are present', () => {
- let contents = fs.readFileSync(whitespace, 'utf8')
+ test('does not add newlines when no newlines are present', async () => {
+ let contents = await fs.readFile(whitespace, 'utf8')
contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion)
const $ = cheerio.load(contents)
expect($('.example5').text()).toBe('\n Alpha\n')
diff --git a/tests/content/site-data-references.js b/tests/content/site-data-references.js
index c6f0a019bd56..045e33843ba4 100644
--- a/tests/content/site-data-references.js
+++ b/tests/content/site-data-references.js
@@ -3,10 +3,12 @@ const loadSiteData = require('../../lib/site-data')
const { loadPages } = require('../../lib/pages')
const getDataReferences = require('../../lib/get-liquid-data-references')
const frontmatter = require('@github-docs/frontmatter')
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
describe('data references', () => {
+ jest.setTimeout(60 * 1000)
+
let data, pages
beforeAll(async (done) => {
@@ -33,34 +35,34 @@ describe('data references', () => {
expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0)
})
- test('every data reference found in metadata of English content files is defined and has a value', () => {
+ test('every data reference found in metadata of English content files is defined and has a value', async () => {
let errors = []
expect(pages.length).toBeGreaterThan(0)
- pages.forEach(page => {
+ await Promise.all(pages.map(async page => {
const metadataFile = path.join('content', page.relativePath)
- const fileContents = fs.readFileSync(path.join(__dirname, '../..', metadataFile))
+ const fileContents = await fs.readFile(path.join(__dirname, '../..', metadataFile))
const { data: metadata } = frontmatter(fileContents, { filepath: page.fullPath })
const metadataRefs = getDataReferences(JSON.stringify(metadata))
metadataRefs.forEach(key => {
const value = get(data.en, key)
if (typeof value !== 'string') errors.push({ key, value, metadataFile })
})
- })
+ }))
errors = uniqWith(errors, isEqual) // remove duplicates
expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0)
})
- test('every data reference found in English reusable files is defined and has a value', () => {
+ test('every data reference found in English reusable files is defined and has a value', async () => {
let errors = []
const allReusables = data.en.site.data.reusables
const reusables = Object.values(allReusables)
expect(reusables.length).toBeGreaterThan(0)
- reusables.forEach(reusablesPerFile => {
+ await Promise.all(reusables.map(async reusablesPerFile => {
let reusableFile = path.join(__dirname, '../../data/reusables/', getFilenameByValue(allReusables, reusablesPerFile))
- reusableFile = getFilepath(reusableFile)
+ reusableFile = await getFilepath(reusableFile)
const reusableRefs = getDataReferences(JSON.stringify(reusablesPerFile))
@@ -68,21 +70,21 @@ describe('data references', () => {
const value = get(data.en, key)
if (typeof value !== 'string') errors.push({ key, value, reusableFile })
})
- })
+ }))
errors = uniqWith(errors, isEqual) // remove duplicates
expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0)
})
- test('every data reference found in English variable files is defined and has a value', () => {
+ test('every data reference found in English variable files is defined and has a value', async () => {
let errors = []
const allVariables = data.en.site.data.variables
const variables = Object.values(allVariables)
expect(variables.length).toBeGreaterThan(0)
- variables.forEach(variablesPerFile => {
+ await Promise.all(variables.map(async variablesPerFile => {
let variableFile = path.join(__dirname, '../../data/variables/', getFilenameByValue(allVariables, variablesPerFile))
- variableFile = getFilepath(variableFile)
+ variableFile = await getFilepath(variableFile)
const variableRefs = getDataReferences(JSON.stringify(variablesPerFile))
@@ -90,7 +92,7 @@ describe('data references', () => {
const value = get(data.en, key)
if (typeof value !== 'string') errors.push({ key, value, variableFile })
})
- })
+ }))
errors = uniqWith(errors, isEqual) // remove duplicates
expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0)
@@ -102,10 +104,13 @@ function getFilenameByValue (object, value) {
}
// if path exists, assume it's a directory; otherwise, assume a YML extension
-function getFilepath (filepath) {
- filepath = fs.existsSync(filepath)
- ? filepath + '/'
- : filepath + '.yml'
+async function getFilepath (filepath) {
+ try {
+ await fs.stat(filepath)
+ filepath = filepath + '/'
+ } catch (_) {
+ filepath = filepath + '.yml'
+ }
// we only need the relative path
return filepath.replace(path.join(__dirname, '../../'), '')
diff --git a/tests/content/site-data.js b/tests/content/site-data.js
index e563df27d3a9..adbdaa7596eb 100644
--- a/tests/content/site-data.js
+++ b/tests/content/site-data.js
@@ -45,11 +45,11 @@ describe('siteData module (English)', () => {
// TODO: re-enable once Janky flakyness is resolved
test.skip('backfills missing translated site data with English values', async () => {
const newFile = path.join(__dirname, '../../data/newfile.yml')
- fs.writeFileSync(newFile, 'newvalue: bar')
+ await fs.writeFile(newFile, 'newvalue: bar')
const data = await loadSiteData()
expect(get(data, 'en.site.data.newfile.newvalue')).toEqual('bar')
expect(get(data, 'ja.site.data.newfile.newvalue')).toEqual('bar')
- fs.unlinkSync(newFile)
+ await fs.unlink(newFile)
})
test('all Liquid templating is valid', async () => {
diff --git a/tests/graphql/build-changelog-test.js b/tests/graphql/build-changelog-test.js
index 1a55d59bab9c..4620d4aeee67 100644
--- a/tests/graphql/build-changelog-test.js
+++ b/tests/graphql/build-changelog-test.js
@@ -1,6 +1,6 @@
const yaml = require('js-yaml')
const { createChangelogEntry, cleanPreviewTitle, previewAnchor, prependDatedEntry } = require('../../script/graphql/build-changelog')
-const fs = require('fs')
+const fs = require('fs').promises
const MockDate = require('mockdate')
const expectedChangelogEntry = require('../fixtures/changelog-entry')
const expectedUpdatedChangelogFile = require('../fixtures/updated-changelog-file')
@@ -111,18 +111,18 @@ describe('updating the changelog file', () => {
MockDate.reset()
})
- it('modifies the entry object and the file on disk', () => {
+ it('modifies the entry object and the file on disk', async () => {
const testTargetPath = 'tests/graphql/example_changelog.json'
- const previousContents = fs.readFileSync(testTargetPath)
+ const previousContents = await fs.readFile(testTargetPath)
const exampleEntry = { someStuff: true }
const expectedDate = '2020-11-20'
MockDate.set(expectedDate)
prependDatedEntry(exampleEntry, testTargetPath)
- const newContents = fs.readFileSync(testTargetPath, 'utf8')
+ const newContents = await fs.readFile(testTargetPath, 'utf8')
// reset the file:
- fs.writeFileSync(testTargetPath, previousContents)
+ await fs.writeFile(testTargetPath, previousContents)
expect(exampleEntry).toEqual({ someStuff: true, date: expectedDate })
expect(JSON.parse(newContents)).toEqual(expectedUpdatedChangelogFile)
diff --git a/tests/meta/orphan-tests.js b/tests/meta/orphan-tests.js
index 770b10389cfd..9d561140c6fc 100644
--- a/tests/meta/orphan-tests.js
+++ b/tests/meta/orphan-tests.js
@@ -1,20 +1,28 @@
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
+const { filter: asyncFilter } = require('async')
describe('check for orphan tests', () => {
- test('all tests are in sub-directories', () => {
+ test('all tests are in sub-directories', async () => {
// A known list of exceptions that can live outside of directories
const EXCEPTIONS = ['README.md']
const pathToTests = path.join(process.cwd(), 'tests')
// Get a list of files/directories in `/tests`
- const testDirectory = fs.readdirSync(pathToTests)
+ const testDirectory = await fs.readdir(pathToTests)
- const filteredList = testDirectory
+ let filteredList = testDirectory
// Filter out our exceptions
.filter(item => !EXCEPTIONS.includes(item))
- // Don't include directories
- .filter(item => !fs.statSync(path.join(pathToTests, item)).isDirectory())
+ // Don't include directories
+ filteredList = await asyncFilter(
+ filteredList,
+ async item => !(
+ await fs.stat(
+ path.join(pathToTests, item)
+ )
+ ).isDirectory()
+ )
expect(filteredList).toHaveLength(0)
})
diff --git a/tests/rendering/rest.js b/tests/rendering/rest.js
index d26e1b74ad40..34a9428a045b 100644
--- a/tests/rendering/rest.js
+++ b/tests/rendering/rest.js
@@ -1,4 +1,4 @@
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
const { difference, isPlainObject } = require('lodash')
const { getJSON } = require('../helpers/supertest')
@@ -17,7 +17,7 @@ describe('REST references docs', () => {
test('markdown file exists for every operationId prefix in the api.github.com schema', async () => {
const { categories } = require('../../lib/rest')
const referenceDir = path.join(__dirname, '../../content/rest/reference')
- const filenames = fs.readdirSync(referenceDir)
+ const filenames = (await fs.readdir(referenceDir))
.filter(filename => !excludeFromResourceNameCheck.find(excludedFile => filename.endsWith(excludedFile)))
.map(filename => filename.replace('.md', ''))
diff --git a/tests/routing/redirects.js b/tests/routing/redirects.js
index 740cd67d55d0..b41a0888a8c1 100644
--- a/tests/routing/redirects.js
+++ b/tests/routing/redirects.js
@@ -17,8 +17,8 @@ describe('redirects', () => {
done()
})
- test('page.redirects is an array', () => {
- const page = new Page({
+ test('page.redirects is an array', async () => {
+ const page = await Page.init({
relativePath: 'github/collaborating-with-issues-and-pull-requests/about-branches.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -26,8 +26,8 @@ describe('redirects', () => {
expect(isPlainObject(page.redirects)).toBe(true)
})
- test('dotcom homepage page.redirects', () => {
- const page = new Page({
+ test('dotcom homepage page.redirects', async () => {
+ const page = await Page.init({
relativePath: 'github/index.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -41,7 +41,7 @@ describe('redirects', () => {
})
test('converts single `redirect_from` strings values into arrays', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'github/collaborating-with-issues-and-pull-requests/about-conversations-on-github.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
diff --git a/tests/unit/early-access.js b/tests/unit/early-access.js
index f8ad0b3b88fd..80aa48373f95 100644
--- a/tests/unit/early-access.js
+++ b/tests/unit/early-access.js
@@ -1,4 +1,4 @@
-const fs = require('fs')
+const fs = require('fs').promises
const path = require('path')
const { GITHUB_ACTIONS, GITHUB_REPOSITORY } = process.env
@@ -7,17 +7,17 @@ const testViaActionsOnly = runningActionsOnInternalRepo ? test : test.skip
describe('cloning early-access', () => {
testViaActionsOnly('the content directory exists', async () => {
- const eaContentDir = path.join(process.cwd(), 'content/early-access')
- expect(fs.existsSync(eaContentDir)).toBe(true)
+ const eaDir = path.join(process.cwd(), 'content/early-access')
+ expect(await fs.stat(eaDir)).toBeTruthy()
})
testViaActionsOnly('the data directory exists', async () => {
- const eaContentDir = path.join(process.cwd(), 'data/early-access')
- expect(fs.existsSync(eaContentDir)).toBe(true)
+ const eaDir = path.join(process.cwd(), 'data/early-access')
+ expect(await fs.stat(eaDir)).toBeTruthy()
})
testViaActionsOnly('the assets/images directory exists', async () => {
- const eaContentDir = path.join(process.cwd(), 'assets/images/early-access')
- expect(fs.existsSync(eaContentDir)).toBe(true)
+ const eaDir = path.join(process.cwd(), 'assets/images/early-access')
+ expect(await fs.stat(eaDir)).toBeTruthy()
})
})
diff --git a/tests/unit/find-page.js b/tests/unit/find-page.js
index bb422df1b3e5..5772db5f010d 100644
--- a/tests/unit/find-page.js
+++ b/tests/unit/find-page.js
@@ -8,7 +8,7 @@ describe('find page', () => {
jest.setTimeout(1000 * 1000)
test('falls back to the English page if it can\'t find a localized page', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'page-that-does-not-exist-in-translations-dir.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
@@ -24,7 +24,7 @@ describe('find page', () => {
})
test('follows redirects', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'page-with-redirects.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
diff --git a/tests/unit/liquid-helpers.js b/tests/unit/liquid-helpers.js
index ee6b8d3ecf17..41c54a2e3d27 100644
--- a/tests/unit/liquid-helpers.js
+++ b/tests/unit/liquid-helpers.js
@@ -5,6 +5,8 @@ const { set } = require('lodash')
const nonEnterpriseDefaultVersion = require('../../lib/non-enterprise-default-version')
describe('liquid helper tags', () => {
+ jest.setTimeout(60 * 1000)
+
const context = {}
let pageMap
beforeAll(async (done) => {
diff --git a/tests/unit/page.js b/tests/unit/page.js
index 5d1b46a0c3ad..44f98c94a567 100644
--- a/tests/unit/page.js
+++ b/tests/unit/page.js
@@ -15,14 +15,14 @@ const opts = {
}
describe('Page class', () => {
- test('preserves file path info', () => {
- const page = new Page(opts)
+ test('preserves file path info', async () => {
+ const page = await Page.init(opts)
expect(page.relativePath).toBe('github/collaborating-with-issues-and-pull-requests/about-branches.md')
expect(page.fullPath.includes(page.relativePath)).toBe(true)
})
- test('does not error out on translated TOC with no links', () => {
- const page = new Page({
+ test('does not error out on translated TOC with no links', async () => {
+ const page = await Page.init({
relativePath: 'translated-toc-with-no-links-index.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'ja'
@@ -31,30 +31,34 @@ describe('Page class', () => {
})
describe('showMiniToc page property', () => {
- const article = new Page({
- relativePath: 'sample-article.md',
- basePath: path.join(__dirname, '../fixtures'),
- languageCode: 'en'
- })
+ let article, articleWithFM, tocPage, mapTopic
- const articleWithFM = new Page({
- showMiniToc: false,
- relativePath: article.relativePath,
- basePath: article.basePath,
- languageCode: article.languageCode
- })
+ beforeAll(async () => {
+ article = await Page.init({
+ relativePath: 'sample-article.md',
+ basePath: path.join(__dirname, '../fixtures'),
+ languageCode: 'en'
+ })
- const tocPage = new Page({
- relativePath: 'sample-toc-index.md',
- basePath: path.join(__dirname, '../fixtures'),
- languageCode: 'en'
- })
+ articleWithFM = await Page.init({
+ showMiniToc: false,
+ relativePath: article.relativePath,
+ basePath: article.basePath,
+ languageCode: article.languageCode
+ })
+
+ tocPage = await Page.init({
+ relativePath: 'sample-toc-index.md',
+ basePath: path.join(__dirname, '../fixtures'),
+ languageCode: 'en'
+ })
- const mapTopic = new Page({
- mapTopic: true,
- relativePath: article.relativePath,
- basePath: article.basePath,
- languageCode: article.languageCode
+ mapTopic = await Page.init({
+ mapTopic: true,
+ relativePath: article.relativePath,
+ basePath: article.basePath,
+ languageCode: article.languageCode
+ })
})
test('is true by default on articles', () => {
@@ -76,7 +80,7 @@ describe('Page class', () => {
describe('page.render(context)', () => {
test('rewrites links to include the current language prefix and version', async () => {
- const page = new Page(opts)
+ const page = await Page.init(opts)
const context = {
page: { version: nonEnterpriseDefaultVersion },
currentVersion: nonEnterpriseDefaultVersion,
@@ -99,7 +103,7 @@ describe('Page class', () => {
})
test('rewrites links in the intro to include the current language prefix and version', async () => {
- const page = new Page(opts)
+ const page = await Page.init(opts)
page.rawIntro = '[Pull requests](/articles/about-pull-requests)'
const context = {
page: { version: nonEnterpriseDefaultVersion },
@@ -114,7 +118,7 @@ describe('Page class', () => {
})
test('does not rewrite links that include deprecated enterprise release numbers', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'admin/enterprise-management/migrating-from-github-enterprise-1110x-to-2123.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -133,7 +137,7 @@ describe('Page class', () => {
})
test('does not rewrite links to external redirects', async () => {
- const page = new Page(opts)
+ const page = await Page.init(opts)
page.markdown = `${page.markdown}\n\nSee [Capistrano](/capistrano).`
const context = {
page: { version: nonEnterpriseDefaultVersion },
@@ -150,7 +154,7 @@ describe('Page class', () => {
// But they don't have access to our currently supported versions, which we're testing here.
// This test ensures that this works as expected: {% if enterpriseServerVersions contains currentVersion %}
test('renders the expected Enterprise Server versioned content', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'page-versioned-for-all-enterprise-releases.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
@@ -184,27 +188,27 @@ describe('Page class', () => {
})
})
- test('preserves `languageCode`', () => {
- const page = new Page(opts)
+ test('preserves `languageCode`', async () => {
+ const page = await Page.init(opts)
expect(page.languageCode).toBe('en')
})
- test('parentProductId getter', () => {
- let page = new Page({
+ test('parentProductId getter', async () => {
+ let page = await Page.init({
relativePath: 'github/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'en'
})
expect(page.parentProductId).toBe('github')
- page = new Page({
+ page = await Page.init({
relativePath: 'actions/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'en'
})
expect(page.parentProductId).toBe('actions')
- page = new Page({
+ page = await Page.init({
relativePath: 'admin/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'en'
@@ -213,26 +217,26 @@ describe('Page class', () => {
})
describe('permalinks', () => {
- test('is an array', () => {
- const page = new Page(opts)
+ test('is an array', async () => {
+ const page = await Page.init(opts)
expect(Array.isArray(page.permalinks)).toBe(true)
})
- test('has a key for every supported enterprise version (and no deprecated versions)', () => {
- const page = new Page(opts)
+ test('has a key for every supported enterprise version (and no deprecated versions)', async () => {
+ const page = await Page.init(opts)
const pageVersions = page.permalinks.map(permalink => permalink.pageVersion)
expect(enterpriseServerReleases.supported.every(version => pageVersions.includes(`enterprise-server@${version}`))).toBe(true)
expect(enterpriseServerReleases.deprecated.every(version => !pageVersions.includes(`enterprise-server@${version}`))).toBe(true)
})
- test('sets versioned values', () => {
- const page = new Page(opts)
+ test('sets versioned values', async () => {
+ const page = await Page.init(opts)
expect(page.permalinks.find(permalink => permalink.pageVersion === nonEnterpriseDefaultVersion).href).toBe(`/en/${nonEnterpriseDefaultVersion}/github/collaborating-with-issues-and-pull-requests/about-branches`)
expect(page.permalinks.find(permalink => permalink.pageVersion === `enterprise-server@${enterpriseServerReleases.oldestSupported}`).href).toBe(`/en/enterprise-server@${enterpriseServerReleases.oldestSupported}/github/collaborating-with-issues-and-pull-requests/about-branches`)
})
- test('homepage permalinks', () => {
- const page = new Page({
+ test('homepage permalinks', async () => {
+ const page = await Page.init({
relativePath: 'index.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -242,8 +246,8 @@ describe('Page class', () => {
expect(page.permalinks.find(permalink => permalink.pageVersion === 'homepage').href).toBe('/en')
})
- test('permalinks for dotcom-only pages', () => {
- const page = new Page({
+ test('permalinks for dotcom-only pages', async () => {
+ const page = await Page.init({
relativePath: 'github/getting-started-with-github/signing-up-for-a-new-github-account.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -252,8 +256,8 @@ describe('Page class', () => {
expect(page.permalinks.length).toBe(1)
})
- test('permalinks for enterprise-only pages', () => {
- const page = new Page({
+ test('permalinks for enterprise-only pages', async () => {
+ const page = await Page.init({
relativePath: 'products/admin/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
@@ -264,8 +268,8 @@ describe('Page class', () => {
expect(pageVersions.includes(nonEnterpriseDefaultVersion)).toBe(false)
})
- test('permalinks for non-GitHub.com products without Enterprise versions', () => {
- const page = new Page({
+ test('permalinks for non-GitHub.com products without Enterprise versions', async () => {
+ const page = await Page.init({
relativePath: 'products/actions/some-category/some-article.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
@@ -274,8 +278,8 @@ describe('Page class', () => {
expect(page.permalinks.length).toBe(1)
})
- test('permalinks for non-GitHub.com products with Enterprise versions', () => {
- const page = new Page({
+ test('permalinks for non-GitHub.com products with Enterprise versions', async () => {
+ const page = await Page.init({
relativePath: '/insights/installing-and-configuring-github-insights/about-github-insights.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -318,7 +322,7 @@ describe('Page class', () => {
})
test('fixes translated frontmatter that includes verdadero', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'article-with-mislocalized-frontmatter.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'ja'
@@ -333,7 +337,7 @@ describe('Page class', () => {
// Note this test will go out of date when we deprecate 2.20
test('pages that apply to newer enterprise versions', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'github/administering-a-repository/comparing-releases.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -343,7 +347,7 @@ describe('Page class', () => {
})
test('index page', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'index.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -352,7 +356,7 @@ describe('Page class', () => {
})
test('enterprise admin index page', async () => {
- const page = new Page({
+ const page = await Page.init({
relativePath: 'admin/index.md',
basePath: path.join(__dirname, '../../content'),
languageCode: 'en'
@@ -366,50 +370,50 @@ describe('Page class', () => {
describe('catches errors thrown in Page class', () => {
test('frontmatter parsing error', () => {
- function getPage () {
- return new Page({
+ async function getPage () {
+ return await Page.init({
relativePath: 'page-with-frontmatter-error.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
})
}
- expect(getPage).toThrowError('invalid frontmatter entry')
+ expect(getPage).rejects.toThrowError('invalid frontmatter entry')
})
test('missing versions frontmatter', () => {
- function getPage () {
- return new Page({
+ async function getPage () {
+ return await Page.init({
relativePath: 'page-with-missing-product-versions.md',
basePath: path.join(__dirname, '../fixtures'),
languageCode: 'en'
})
}
- expect(getPage).toThrowError('versions')
+ expect(getPage).rejects.toThrowError('versions')
})
test('English page with a version in frontmatter that its parent product is not available in', () => {
- function getPage () {
- return new Page({
+ async function getPage () {
+ return await Page.init({
relativePath: 'admin/some-category/some-article-with-mismatched-versions-frontmatter.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'en'
})
}
- expect(getPage).toThrowError(/`versions` frontmatter.*? product is not available in/)
+ expect(getPage).rejects.toThrowError(/`versions` frontmatter.*? product is not available in/)
})
test('non-English page with a version in frontmatter that its parent product is not available in', () => {
- function getPage () {
- return new Page({
+ async function getPage () {
+ return await Page.init({
relativePath: 'admin/some-category/some-article-with-mismatched-versions-frontmatter.md',
basePath: path.join(__dirname, '../fixtures/products'),
languageCode: 'es'
})
}
- expect(getPage).toThrowError(/`versions` frontmatter.*? product is not available in/)
+ expect(getPage).rejects.toThrowError(/`versions` frontmatter.*? product is not available in/)
})
})
diff --git a/tests/unit/pages.js b/tests/unit/pages.js
index f27b73ff1be2..bb405b5e9c61 100644
--- a/tests/unit/pages.js
+++ b/tests/unit/pages.js
@@ -10,6 +10,8 @@ const entities = new Entities()
const { chain, difference } = require('lodash')
describe('pages module', () => {
+ jest.setTimeout(60 * 1000)
+
let pages
beforeAll(async (done) => {
{% data ui.toc.popular_articles %}
{{ link.title }}
-
+ {% endif %}
{% data ui.toc.whats_new %}
- View all {% octicon "arrow-right" height="14" class="v-align-middle" %} + {% if page.changelog %} +
+
-
+
+ {% data ui.toc.whats_new %}
+ View all {% octicon "arrow-right" height="14" class="v-align-middle" %} +-
+ {% for link in page.changelog %}
+
-
+
+
{{ link.title }} →
+ + +
+ {% endfor %}
+
-
- {% for link in page.changelog %}
-
-
-
-
{{ link.title }} →
- - -
- {% endfor %}
-
admin:enterprise scope to use this endpoint.web - returns web (non-Git) eventsgit - returns Git eventsall - returns both web and Git eventsweb.curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/enterprises/ENTERPRISE/audit-logawait octokit.request('GET /enterprises/{enterprise}/audit-log', {\n enterprise: 'enterprise'\n})\nadmin:enterprise scope.[\n {\n \"@timestamp\": 1606929874512,\n \"action\": \"team.add_member\",\n \"actor\": \"octocat\",\n \"created_at\": 1606929874512,\n \"org\": \"octo-corp\",\n \"team\": \"octo-corp/example-team\",\n \"user\": \"monalisa\"\n },\n {\n \"@timestamp\": 1606507117008,\n \"action\": \"org.create\",\n \"actor\": \"octocat\",\n \"created_at\": 1606507117008,\n \"org\": \"octocat-test-org\"\n },\n {\n \"@timestamp\": 1605719148837,\n \"action\": \"repo.destroy\",\n \"actor\": \"monalisa\",\n \"created_at\": 1605719148837,\n \"org\": \"mona-org\",\n \"repo\": \"mona-org/mona-test-repo\",\n \"visibility\": \"private\"\n }\n]\nvisibility for repository access is set to selected. The visibility is set when you Create or update an organization secret. You must authenticate using an access token with the admin:org scope to use this endpoint. GitHub Apps must have the secrets organization permission to use this endpoint.web - returns web (non-Git) eventsgit - returns Git eventsall - returns both web and Git eventsweb.curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/orgs/ORG/audit-logawait octokit.request('GET /orgs/{org}/audit-log', {\n org: 'org'\n})\nadmin:org scope. GitHub Apps must have the organization_administration read permission to use this endpoint.[\n {\n \"@timestamp\": 1606929874512,\n \"action\": \"team.add_member\",\n \"actor\": \"octocat\",\n \"created_at\": 1606929874512,\n \"org\": \"octo-corp\",\n \"team\": \"octo-corp/example-team\",\n \"user\": \"monalisa\"\n },\n {\n \"@timestamp\": 1606507117008,\n \"action\": \"org.create\",\n \"actor\": \"octocat\",\n \"created_at\": 1606507117008,\n \"org\": \"octocat-test-org\"\n },\n {\n \"@timestamp\": 1605719148837,\n \"action\": \"repo.destroy\",\n \"actor\": \"monalisa\",\n \"created_at\": 1605719148837,\n \"org\": \"mona-org\",\n \"repo\": \"mona-org/mona-test-repo\",\n \"visibility\": \"private\"\n }\n]\n