From 98d4febba9c6c6d83dea846df4af6e14b6febd7b Mon Sep 17 00:00:00 2001 From: Steve Guntrip <12534592+stevecat@users.noreply.github.com> Date: Mon, 14 Feb 2022 13:52:35 +0000 Subject: [PATCH] Updates to Projects --- .../best-practices-for-managing-projects.md | 14 +++++++ .../creating-a-project.md | 4 ++ .../managing-access-to-projects.md | 12 +++--- .../quickstart.md | 4 ++ .../using-the-api-to-manage-projects.md | 37 +++++++++++++++++++ .../reusables/projects/project-description.md | 10 +++++ 6 files changed, 75 insertions(+), 6 deletions(-) create mode 100644 data/reusables/projects/project-description.md diff --git a/content/issues/trying-out-the-new-projects-experience/best-practices-for-managing-projects.md b/content/issues/trying-out-the-new-projects-experience/best-practices-for-managing-projects.md index ad79f17b59..be212dc476 100644 --- a/content/issues/trying-out-the-new-projects-experience/best-practices-for-managing-projects.md +++ b/content/issues/trying-out-the-new-projects-experience/best-practices-for-managing-projects.md @@ -27,6 +27,20 @@ To track how smaller issues fit into the larger goal, use task lists, milestones Issues and pull requests include built-in features to let you easily communicate with your collaborators. Use @mentions to alert a person or entire team about a comment. Assign collaborators to issues to communicate responsibility. Link to related issues or pull requests to communicate how they are connected. +## Make use of the description and README + +Use your project's description and README to share information about the project. + +For example: + +- Explaining the purpose of the project. +- Describing the project views and how to use them. +- Including relevant links and people to contact for more information. + +Project READMEs support Markdown which allows you to use images and advanced formatting such as links, lists, and headers. + +For more information, see "[Creating a project (beta)](/issues/trying-out-the-new-projects-experience/creating-a-project#updating-your-project-description-and-readme)." + ## Use views Use project views to look at your project from different angles. diff --git a/content/issues/trying-out-the-new-projects-experience/creating-a-project.md b/content/issues/trying-out-the-new-projects-experience/creating-a-project.md index 9f0e4cc09d..6c71d9d2f5 100644 --- a/content/issues/trying-out-the-new-projects-experience/creating-a-project.md +++ b/content/issues/trying-out-the-new-projects-experience/creating-a-project.md @@ -25,6 +25,10 @@ Projects are a customizable collection of items that stay up-to-date with {% dat {% data reusables.projects.create-user-project %} +## Updating your project description and README + +{% data reusables.projects.project-description %} + ## Adding items to your project Your project can track draft issues, issues, and pull requests. diff --git a/content/issues/trying-out-the-new-projects-experience/managing-access-to-projects.md b/content/issues/trying-out-the-new-projects-experience/managing-access-to-projects.md index 0e92893d8d..c0e785f37e 100644 --- a/content/issues/trying-out-the-new-projects-experience/managing-access-to-projects.md +++ b/content/issues/trying-out-the-new-projects-experience/managing-access-to-projects.md @@ -15,7 +15,7 @@ topics: ## About project access -Admins of organization-level projects can manage access for the entire organization, for teams, and for individual organization members. +Admins of organization-level projects can manage access for the entire organization, for teams, for individual organization members, and for outside collaborators. Admins of user-level projects can invite individual collaborators and manage their access. @@ -37,18 +37,18 @@ The default base role is `write`, meaning that everyone in the organization can ### Managing access for teams and individual members of your organization -You can also add teams, and individual organization members, as collaborators. For more information, see "[About teams](/organizations/organizing-members-into-teams/about-teams)." +You can also add teams, external collaborators, and individual organization members as collaborators for an organization-level project. For more information, see "[About teams](/organizations/organizing-members-into-teams/about-teams)." -You can only invite an individual user to collaborate on your organization-level project if they are a member of the organization. +You can only invite an individual user to collaborate on your organization-level project if they are already a member of the organization or an outside collaborator on at least one repository in the organization. {% data reusables.projects.project-settings %} 1. Click **Manage access**. -1. Under **Invite collaborators**, search for the team or organization member that you want to invite. -1. Select the role for the collaborator. +2. Under **Invite collaborators**, search for the team or individual user that you want to invite. +3. Select the role for the collaborator. - **Read**: The team or individual can view the project. - **Write**: The team or individual can view and edit the project. - **Admin**: The team or individual can view, edit, and add new collaborators to the project. -1. Click **Invite**. +4. Click **Invite**. ### Managing access of an existing collaborator on your project diff --git a/content/issues/trying-out-the-new-projects-experience/quickstart.md b/content/issues/trying-out-the-new-projects-experience/quickstart.md index 35106a7f2e..3b08dca27d 100644 --- a/content/issues/trying-out-the-new-projects-experience/quickstart.md +++ b/content/issues/trying-out-the-new-projects-experience/quickstart.md @@ -35,6 +35,10 @@ First, create an organization project or a user project. {% data reusables.projects.create-user-project %} +## Setting your project description and README + +{% data reusables.projects.project-description %} + ## Adding issues to your project Next, add a few issues to your project. diff --git a/content/issues/trying-out-the-new-projects-experience/using-the-api-to-manage-projects.md b/content/issues/trying-out-the-new-projects-experience/using-the-api-to-manage-projects.md index 30113d0498..fa774f0930 100644 --- a/content/issues/trying-out-the-new-projects-experience/using-the-api-to-manage-projects.md +++ b/content/issues/trying-out-the-new-projects-experience/using-the-api-to-manage-projects.md @@ -365,6 +365,43 @@ The response will contain the node ID of the newly created item. If you try to add an item that already exists, the existing item ID is returned instead. +### Updating a project's settings + +The following example will update your project's settings. Replace `PROJECT_ID` with the node ID of your project. Set `public` to `true` to make your project public on {% data variables.product.product_name %}. Modify `description` to make changes to your project's README. + +{% curl %} +```shell +curl --request POST \ +--url https://api.github.com/graphql \ +--header 'Authorization: token TOKEN' \ +--data '{"query":"mutation { updateProjectNext(input: { projectId: \"PROJECT_ID\", title: \"Project title\", public: false, description: \"# Project README\n\nA long description\", shortDescription: \"A short description\"}) { projectNext { id, title, description, shortDescription }}}"}' +``` +{% endcurl %} + +{% cli %} +```shell +gh api graphql -f query=' + mutation { + updateProjectNext( + input: { + projectId: "PROJECT_ID", + title: "Project title", + public: false, + description: "# Project README\n\nA long description", + shortDescription: "A short description" + } + ) { + projectNext { + id + title + description + shortDescription + } + } + }' +``` +{% endcli %} + ### Updating a custom text, number, or date field The following example will update the value of a date field for an item. Replace `PROJECT_ID` with the node ID of your project. Replace `ITEM_ID` with the node ID of the item you want to update. Replace `FIELD_ID` with the ID of the field that you want to update. diff --git a/data/reusables/projects/project-description.md b/data/reusables/projects/project-description.md new file mode 100644 index 0000000000..e393f00aac --- /dev/null +++ b/data/reusables/projects/project-description.md @@ -0,0 +1,10 @@ +You can set your project's description and README to share the purpose of your project, provide instructions on how to use the project, and include any relevant links. + +{% data reusables.projects.project-settings %} +1. To add a short description to your project, under "Add a description", type your description in the text box and click **Save**. +1. To update your project's README, under "README", type your content in the text box. + - You can format your README using Markdown. For more information, see "[Basic writing and formatting syntax](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)." + - To toggle between the text box and a preview of your changes, click {% octicon "eye" aria-label="The preview icon" %} or {% octicon "pencil" aria-label="The edit icon" %}. +1. To save changes to your README, click **Save**. + +You can view and make quick changes to your project description and README by navigating to your project and clicking {% octicon "sidebar-expand" aria-label="The sidebar icon" %} in the top right. \ No newline at end of file