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.

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

Convert README and CONTRIBUTING from Markdown to AsciiDoc #7527

Merged
merged 2 commits into from
Dec 17, 2022

Conversation

lemeurherve
Copy link
Member

@lemeurherve lemeurherve commented Dec 15, 2022

Follow-up of my first (misplaced) suggestions on the "Disambiguate and document the closure process" pull request: #7516 (comment)

This PR converts the existing two Markdown documents present in the root folder to Asciidoc, in order to be able to move the /docs/MAINTAINERS.adoc file in the root folder too as it's alone in this /docs/ folder. (Subsequent PR: #7528)

Testing done

Visual inspection and comparison of the rendered AsciiDoc (README.adoc and CONTRIBUTING.adoc) with the original Markdown to confirm there were no rendering errors.

Notes / compromises concerning both documents:

GitHub renders Asciidoc with a bigger line spacing than Markdown.
image
image

Concerning CONTRIBUTING:

The "exclamation" Asciidoc render at the beginning differs from the Markdown one, I didn't find a way to include this emoticon without the block. Open to alternatives.
image
image
The IntelliJ listed options are now correctly displayed in Asciidoc.
image
image
As there can be only one "level 0" section, I had to change the level of the "Links" section title at the end.
image
image

Proposed changelog entries

N/A

Proposed upgrade guidelines

N/A

Submitter checklist

  • The Jira issue, if it exists, is well-described.
  • The changelog entries and upgrade guidelines are appropriate for the audience affected by the change (users or developers, depending on the change) and are in the imperative mood (see examples).
    • Fill in the Proposed upgrade guidelines section only if there are breaking changes or changes that may require extra steps from users during upgrade.
  • There is automated testing or an explanation as to why this change has no tests.
  • New public classes, fields, and methods are annotated with @Restricted or have @since TODO Javadocs, as appropriate.
  • New deprecations are annotated with @Deprecated(since = "TODO") or @Deprecated(forRemoval = true, since = "TODO"), if applicable.
  • New or substantially changed JavaScript is not defined inline and does not call eval to ease future introduction of Content Security Policy (CSP) directives (see documentation).
  • For dependency updates, there are links to external changelogs and, if possible, full differentials.
  • For new APIs and extension points, there is a link to at least one consumer.

Desired reviewers

@basil

Maintainer checklist

Before the changes are marked as ready-for-merge:

  • There are at least two (2) approvals for the pull request and no outstanding requests for change.
  • Conversations in the pull request are over, or it is explicit that a reviewer is not blocking the change.
  • Changelog entries in the pull request title and/or Proposed changelog entries are accurate, human-readable, and in the imperative mood.
  • Proper changelog labels are set so that the changelog can be generated automatically.
  • If the change needs additional upgrade steps from users, the upgrade-guide-needed label is set and there is a Proposed upgrade guidelines section in the pull request title (see example).
  • If it would make sense to backport the change to LTS, a Jira issue must exist, be a Bug or Improvement, and be labeled as lts-candidate to be considered (see query).

@lemeurherve
Copy link
Member Author

lemeurherve commented Dec 15, 2022

I'm a bit disappointed GitHub didn't keep the "moved" state for the two files like in my first commit ae713a3 specifically isolated for an easier review.

Copy link
Member

@basil basil left a comment

Choose a reason for hiding this comment

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

Very nice! The Jenkins project loves AsciiDoc, so this not only improves consistency within this repository but also consistency with the broader Jenkins ecosystem, such as jenkins-infra/jenkins.io (which heavily relies on AsciiDoc).

CONTRIBUTING.adoc Show resolved Hide resolved
README.adoc Show resolved Hide resolved
@NotMyFault NotMyFault added the skip-changelog Should not be shown in the changelog label Dec 16, 2022
@basil basil requested a review from a team December 16, 2022 16:41
Copy link
Contributor

@MarkEWaite MarkEWaite left a comment

Choose a reason for hiding this comment

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

Looks great to me. One optional comment that the link to friendly issues would probably be better if it opened the friendly issues table rather than the list of friendly issues. That is optional. Thanks!

CONTRIBUTING.adoc Show resolved Hide resolved
@MarkEWaite
Copy link
Contributor

This PR is now ready for merge. We will merge it after approximately 24 hours if there is no negative feedback.

@MarkEWaite MarkEWaite added the ready-for-merge The PR is ready to go, and it will be merged soon if there is no negative feedback label Dec 16, 2022
@basil basil merged commit 48edf2c into jenkinsci:master Dec 17, 2022
@basil basil changed the title Convert README and CONTRIBUTING from Markdown to Asciidoc Convert README and CONTRIBUTING from Markdown to AsciiDoc Dec 17, 2022
@NotMyFault
Copy link
Member

Merging as-is has broken all of our, and third party, links to contributing.md, see Building and Debugging Jenkins on jenkins.io for just one example.

@oleg-nenashev
Copy link
Member

oleg-nenashev commented Dec 17, 2022 via email

NotMyFault added a commit to NotMyFault/jenkins that referenced this pull request Dec 17, 2022
@NotMyFault
Copy link
Member

Created #7533 to revert this for now.

NotMyFault added a commit that referenced this pull request Dec 17, 2022
* Revert "Move `MAINTAINERS` to the root folder (#7528)"

This reverts commit 43e4efb.

* Revert "Convert `README` and `CONTRIBUTING` from Markdown to AsciiDoc (#7527)"

This reverts commit 48edf2c.
@lemeurherve
Copy link
Member Author

lemeurherve commented Dec 17, 2022

I should have though about that, sorry and thanks Alex for taking care of the revert.

I'll rework it next week, maybe something like a redirection for example.
WDYT?

@NotMyFault
Copy link
Member

I'll rework it next week, maybe something like a redirection for example.

Sounds good, I'm open to alternative approaches, that don't break existing URLs for sure. To be fair, I was under the impression GH warrants redirections, maybe that applies to GH pages only 🤷🏻

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
ready-for-merge The PR is ready to go, and it will be merged soon if there is no negative feedback skip-changelog Should not be shown in the changelog
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants