From 2a393aa43a2289dcbb152bd99a3453c5a326d1c9 Mon Sep 17 00:00:00 2001 From: David Enyeart Date: Mon, 13 Sep 2021 17:59:57 -0400 Subject: [PATCH] Update docs for Jira to GitHub issue transition Update docs to indicate that GitHub issues are now used instead of Jira issues. Signed-off-by: David Enyeart --- docs/source/CONTRIBUTING.rst | 65 ++++++++++++++++------------------- docs/source/github/github.rst | 3 +- 2 files changed, 32 insertions(+), 36 deletions(-) diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst index 7938b81e6e0..593cdf33c25 100644 --- a/docs/source/CONTRIBUTING.rst +++ b/docs/source/CONTRIBUTING.rst @@ -19,10 +19,6 @@ As a user: - `Making Feature/Enhancement Proposals`_ - `Reporting bugs`_ -- Help test an upcoming Epic on the - `release roadmap `_. - Contact the Epic assignee via the Jira work item or on - `RocketChat `_. As a writer or information developer: @@ -49,14 +45,14 @@ Jump to `Contributing documentation`_ to get started on your journey. As a developer: - If you only have a little time, consider picking up a - `"help-wanted" `_ task, + `"good first issue" `_ task, see `Fixing issues and working stories`_. - If you can commit to full-time development, either propose a new feature (see `Making Feature/Enhancement Proposals`_) and bring a team to implement it, or join one of the teams working on an existing Epic. If you see an Epic that interests you on the - `release roadmap `_, - contact the Epic assignee via the Jira work item or on `RocketChat `__. + `GitHub epic backlog `_, + contact the Epic assignee via the GitHub issue. Getting a Linux Foundation account ---------------------------------- @@ -65,7 +61,6 @@ In order to participate in the development of the Hyperledger Fabric project, you will need a Linux Foundation account. Once you have a LF ID you will be able to access all the Hyperledger community tools, including -`Jira issue management `__, `RocketChat `__, and the `Wiki `__ (for editing, only). @@ -86,8 +81,7 @@ already have one. 5. Verify that your browser displays the message ``You have successfully validated your e-mail address``. -6. Access `Jira issue management `__, or - `RocketChat `__. +6. Access `RocketChat `__ to confirm access. Contributing documentation -------------------------- @@ -152,7 +146,7 @@ Releases ~~~~~~~~ Fabric provides a release approximately once every four months with new features and improvements. -New feature work is merged to the Fabric master branch on `Github `__. +New feature work is merged to the Fabric main branch on `GitHub `__. Releases branches are created prior to each release so that the code can stabilize while new features continue to get merged to the master branch. Important fixes will also be backported to the most recent LTS (long-term support) release branch, @@ -167,8 +161,8 @@ Minor improvements can be implemented and reviewed via the normal `GitHub pull r This process is intended to provide a consistent and controlled path for major changes to Fabric and other official project components, so that all stakeholders can be confident about the direction in which Fabric is evolving. -To propose a new feature, first, check -`JIRA `__ and the `Fabric RFC repository `__ to be sure that there isn't already an open (or recently closed) proposal for the same functionality. If there isn't, follow `the RFC process `__ to make a proposal. +To propose a new feature, first, check the +`GitHub issues backlog `__ and the `Fabric RFC repository `__ to be sure that there isn't already an open (or recently closed) proposal for the same functionality. If there isn't, follow `the RFC process `__ to make a proposal. Contributor meeting ~~~~~~~~~~~~~~~~~~~ @@ -188,18 +182,18 @@ maintainers meeting for consideration, feedback and acceptance. Release roadmap ~~~~~~~~~~~~~~~ -The Fabric release roadmap of epics is maintained in -`JIRA `__. +The Fabric release roadmap is managed as a list of +`GitHub issues with Epic label `__. Communications ~~~~~~~~~~~~~~ We use `RocketChat `__ for communication and Google Hangouts™ for screen sharing between developers. Our -development planning and prioritization is done in -`JIRA `__, and we take longer running -discussions/decisions to the `mailing -list `__. +development planning and prioritization is done using a +`GitHub Issues ZenHub board `__, and we take longer running +discussions/decisions to the `Fabric contributor meeting `__ +or `mailing list `__. Contribution guide ------------------ @@ -230,8 +224,8 @@ Reporting bugs ~~~~~~~~~~~~~~ If you are a user and you have found a bug, please submit an issue using -`JIRA `__. -Before you create a new JIRA issue, please try to search the existing items to +`GitHub Issues `__. +Before you create a new GitHub issue, please try to search the existing issues to be sure no one else has previously reported it. If it has been previously reported, then you might add a comment that you also are interested in seeing the defect fixed. @@ -241,7 +235,7 @@ the defect fixed. If it has not been previously reported, you may either submit a PR with a well documented commit message describing the defect and the fix, or you -may create a new JIRA. Please try to provide +may create a new GitHub issue. Please try to provide sufficient information for someone else to reproduce the issue. One of the project's maintainers should respond to your issue within 24 hours. If not, please bump the issue with a comment and request that it be @@ -253,18 +247,18 @@ and so on... Submitting your fix ~~~~~~~~~~~~~~~~~~~ -If you just submitted a JIRA for a bug you've discovered, and would like to -provide a fix, we would welcome that gladly! Please assign the JIRA issue to +If you just submitted a GitHub issue for a bug you've discovered, and would like to +provide a fix, we would welcome that gladly! Please assign the GitHub issue to yourself, then submit a pull request (PR). Please refer to :doc:`github/github` for a detailed workflow. Fixing issues and working stories ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Fabric issues and bugs are managed in `JIRA `__. +Fabric issues and bugs are managed in `GitHub issues `__. Review the list of issues and find something that interests you. You could also check the -`"help-wanted" `__ +`"good first issue" `__ list. It is wise to start with something relatively straight forward and achievable, and that no one is already assigned. If no one is assigned, then assign the issue to yourself. Please be considerate and rescind the @@ -272,9 +266,9 @@ assignment if you cannot finish in a reasonable time, or add a comment saying that you are still actively working the issue if you need a little more time. -While Jira tracks a backlog of known issues that could be worked in the future, -if you intend to immediately work on a change that does not yet have a corresponding Jira issue, -you can submit a pull request to `Github `__ without linking to an existing Jira issue. +While GitHub issues tracks a backlog of known issues that could be worked in the future, +if you intend to immediately work on a change that does not yet have a corresponding issue, +you can submit a pull request to `Github `__ without linking to an existing issue. Reviewing submitted Pull Requests (PRs) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -339,12 +333,13 @@ What makes a good pull request? regression, it is much easier to identify the culprit commit than if we have some composite change that impacts more of the code. -- If there is a corresponding Jira issue or bug, include a link to the - Jira issue in the PR summary and commit message. - Why? Because the maintainer that merges the PR will need to close - any corresponding Jira issue. - Also, in many cases, there will be additional discussion around - a proposed change or bug in Jira. +- If there is a corresponding GitHub issue, include a link to the + GitHub issue in the PR summary and commit message. + Why? Because there will often be additional discussion around + a proposed change or bug in the GitHub issue. + Additionally, if you use syntax like "Resolves #" + in the PR summary and commit message, the GitHub issue will + automatically be closed when the PR is merged. - Include unit and integration tests (or changes to existing tests) with every change. This does not mean just happy path testing, diff --git a/docs/source/github/github.rst b/docs/source/github/github.rst index 35c20354639..409e1b06677 100644 --- a/docs/source/github/github.rst +++ b/docs/source/github/github.rst @@ -145,7 +145,8 @@ Perform the following steps to commit and push your code to your forked reposito - one line summary of the work in this commit as title, followed by an empty line - in the commit message body, explain why this change is needed, and how you approached it. This helps reviewers better understand your code and often speeds up the review process. - - link to JIRA item or JIRA number, i.e. FAB-XXXXX + - link to GitHub issue (if exists), using syntax like "Resolves #" so that the + GitHub issue automatically gets linked and closed when the PR gets merged. - (optional) if no new tests are added, how the code is tested .. code::