Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document post-host process #6699

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document post-host process #6699

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 35 additions & 4 deletions content/doc/developer/publishing/requesting-hosting.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,9 @@ The Jenkins project hosts a Jenkins instance to perform continuous integration b
We recommend you set up CI builds for your plugin in the `jenkinsci` GitHub organization by creating a `Jenkinsfile` in your plugin's GitHub repository.
See link:../continuous-integration[the documentation for CI builds] for details how to do this.

== After the hosting acceptance

== Request Upload Permissions
=== Request Upload Permissions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
=== Request Upload Permissions
=== Request upload permissions

adjusting to sentence case so that it is aligned with the other section headers


After your plugin source code has been forked into the `jenkinsci` organization, a pull request will be created for you that adds release permissions, if this doesn't happen you may need to create the request yourself.
link:https://github.com/jenkins-infra/repository-permissions-updater/[Follow the instructions in the README of this repository] to do that.
Expand All @@ -62,12 +63,42 @@ Alternately, you can configure your plugin to be released automatically whenever
In this case you only need write permission to GitHub; you never need local credentials.
Follow link:/redirect/continuous-delivery-of-plugins[this guide] for details.

== Categorize the Plugin
=== Automate your GitHub repository

==== Activate GitHub actions
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

change the hosting bot to do this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you activate actions via the API? I don't mean in settings, but clicking the green surface "I understand my workflows" 🤔

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unsure

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on this page, it appears that GitHub Actions is the name of a product (i.e., a proper noun) and should therefore be capitalized.


During the hosting process, you have included a shared workflow to generate changelogs automatically. Publishing changelogs as GitHub release notes is a good practice to keep your users informed about the changes in your plugin.

To activate the workflow, you need to go to the `Actions` tab of your GitHub repository and click on the `I understand my workflows, go ahead and enable them` button.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here and elsewhere there are usages of backticks for things other than code. Backticks should only be used for inline code.

Follow the next section to create the necessary labels for your pull requests.

==== Create the default labels
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not required as per jenkins-infra/helpdesk#3694 (comment)

The script itself is probably useful for existing repositories


Use the following script to create the default labels for your GitHub repository, used to categorize issues and pull requests and generate changelogs automatically:

The script makes use of `gh`, you may need to install and link:[authenticate](https://cli.github.com/manual/gh_auth_login) first, if you haven't already.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The script makes use […], you may need to install and authenticate […]

These are two independent clauses, each with a subject and verb, without a coordinating conjunction; i.e., a run-on sentence. Suggest using a semicolon instead of a comma or adding a coordinating conjunction.


```sh
https://gist.github.com/NotMyFault/b036718b73f1ad2a96faca315fc8ca68/raw
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An exhaustive list of labels used for release-drafter https://github.com/jenkinsci/.github/blob/master/.github/release-drafter.yml, with the default colors and descriptions.

Copy link
Contributor

@MarkEWaite MarkEWaite Sep 22, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like you want them to execute a shell command. Doesn't that need to be something like:

Suggested change
https://gist.github.com/NotMyFault/b036718b73f1ad2a96faca315fc8ca68/raw
wget -O labels https://gist.github.com/NotMyFault/b036718b73f1ad2a96faca315fc8ca68/raw
bash labels

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thoughts about && bash..., having it as a single command only then 👀

Copy link
Member

@lemeurherve lemeurherve Sep 23, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe store this file in RPU repo and link to the raw version instead of a gist in your personal account?

Also, maybe add a mention about reading the content first before blindly executing a content from Internet? (As an awareness precaution/advice)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As there aren't that much lines in this script, I'm wondering if it wouldn't be better to list them in the doc and tell people to execute them themself.

Having them stored in a script in an official repository has the benefit of being a global reference, but it also give the not so good habit of executing a script from Internet.

I suppose it depends on whether this label list change frequently or not.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe store this file in RPU repo and link to the raw version instead of a gist in your personal account?

Works either way. I thought of linking from the RPU to this part, but we can inline it for sure.

I suppose it depends on whether this label list change frequently or not.

I don't think we have ever changed them for the release-drafter/cd action. I'm mostly using it when modernizing plugins because creating labels, with colors and descriptions always takes a good moment.

```
Enter the repository name of your plugin when prompted.

NOTE: Bear in mind, that the script is intended to overwrite existing labels, to make sure you don't have any outdated labels with different descriptions or colors.

==== Activate dependabot
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on this page, it appears that Dependabot is the name of a product (i.e., a proper noun) and should therefore be capitalized.


Dependabot is a GitHub feature that automatically creates pull requests to update dependencies in your repository. It is a good practice to keep your dependencies up to date, as it helps to avoid security vulnerabilities and compatibility issues.

To activate dependabot, you need to go to the `Settings` tab, followed by `Code security and analysis` tab of your GitHub repository and click on the `Enable` button next to `Dependabot version updates` and `Dependency graph`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#about-version-updates-for-dependencies, it can be activated by the .github/dependabot.yml file in the repository.


Alternatively, you can use link:[renovate](https://www.mend.io/renovate/) too, which is used by plugin maintainers, if you prefer.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on this page, it appears that Renovate is the name of a product (i.e., a proper noun) and should therefore be capitalized.


=== Categorize the Plugin
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The headings elsewhere on this page use sentence case rather than title case, as noted previously by Kevin, so should this heading do the same?


Jenkins shows plugins in categories in the plugin manager and on the link:https://plugins.jenkins.io/[plugins site].
The link:../documentation[plugin documentation guide] includes instructions for link:../documentation#documenting-plugins[documenting], categorizing, and link:../documentation#labeling-plugins[labeling] plugins.

== Integrate with Jira
=== Integrate with Jira

If your chosen issue tracker is Jira, you can setup autolink references, to link from commits directly to the Jenkins Jira issue.
All you need to do is heading to the `Settings` tab of your GitHub repository and add the following configuration to the `Autolink references` section:
Expand All @@ -79,7 +110,7 @@ Target URL: https://issues.jenkins.io/browse/JENKINS-<num>
Commits prefixed with `JENKINS-<num>` will now be linked to the corresponding Jira issue:
image:/images/developer/plugin-development/hosting/jira-auto-reference.png[]

== Join the community
=== Join the community

As a new plugin author, its highly recommended that you join the link:/mailing-lists/[mailing list] to interact with the community and to stay up to date with the latest Jenkins news.

Expand Down