doc: Expand section on Getting Started #19072

MarcoFalke commented at 5:02 PM on May 26, 2020: member

Some random doc changes:

Add sections to docs, so that they can be linked to
Explain that anyone (even maintainers) are allowed to work on good first issues
Expand section on Getting Started slightly

MarcoFalke commented at 5:02 PM on May 26, 2020: member

Changes have been split out from #19071 because they are unrelated

in CONTRIBUTING.md:36 in 336b300dc4 outdated

  32 | +unsure, you might want to leave a comment on the issue first.
  33 | +
  34 | +You may also participate in the weekly
  35 | +[Bitcoin Core PR Review Club](https://bitcoincore.reviews/) meeting.
  36 | +
  37 | +Finally, review and testing is important as well. It gives you an idea of what

adamjonas commented at 5:13 PM on May 26, 2020:

Finally, review and testing are important as well. It gives you an idea of what

in CONTRIBUTING.md:46 in 336b300dc4 outdated

  42 | +
  43 | +### Good First Issue Label
  44 | +
  45 | +The purpose of the `good first issue` label is to highlight which issues are suitable for a new contributor without a deep understanding of the codebase.
  46 | +
  47 | +However, `good first issue`s can be solved by anyone. If they remain unsolved for a longer time, a common contributor might address them.

adamjonas commented at 5:14 PM on May 26, 2020:

consider frequent for common to clarify

in .github/ISSUE_TEMPLATE/good_first_issue.md:10 in 336b300dc4 outdated

   6 | @@ -7,15 +7,14 @@ assignees: ''
   7 |  
   8 |  ---
   9 |  
  10 | +<!-- A good first issue is an uncontroversial issue, that has a more or less unique and obvious solution -->

adamjonas commented at 5:16 PM on May 26, 2020:

<!-- A good first issue is an uncontroversial issue, that has a relatively unique and obvious solution -->

in CONTRIBUTING.md:21 in 336b300dc4 outdated

  13 | @@ -14,15 +14,44 @@ purposes. As such there are repository "maintainers" who are responsible for
  14 |  merging pull requests as well as a "lead maintainer" who is responsible for the
  15 |  release cycle, overall merging, moderation and appointment of maintainers.
  16 |  
  17 | +Getting Started
  18 | +---------------
  19 | +
  20 | +New developers are very welcome and needed. There are a lot of open issues of
  21 | +any difficulty waiting to be fixed. However, before you start contributing,

adamjonas commented at 5:17 PM on May 26, 2020:

varying difficulty waiting to be fixed. However, before you start contributing,

in CONTRIBUTING.md:48 in 336b300dc4 outdated

  44 | +
  45 | +The purpose of the `good first issue` label is to highlight which issues are suitable for a new contributor without a deep understanding of the codebase.
  46 | +
  47 | +However, `good first issue`s can be solved by anyone. If they remain unsolved for a longer time, a common contributor might address them.
  48 | +
  49 | +You do not need to request permission to start working on this. You are encouraged to comment on the issue if you are planning to work on it. This will help other contributors monitor which issues are actively being addressed and is also an effective way to request assistance if and when you need it.

adamjonas commented at 5:21 PM on May 26, 2020:

You do not need to request permission to start working on an issue. However, you are encouraged to leave a comment if you are planning to work on it. This will help other contributors monitor which issues are actively being addressed and is also an effective way to request assistance if and when you need it.

in CONTRIBUTING.md:143 in 336b300dc4 outdated

 132 | @@ -100,18 +133,24 @@ Examples:
 133 |      qt: Add feed bump button
 134 |      log: Fix typo in log message
 135 |  
 136 | +The body of the pull request should contain enough description about what the
 137 | +patch does together with any justification/reasoning. You should include
 138 | +references to any discussions (for example other tickets or mailing list

adamjonas commented at 5:21 PM on May 26, 2020:

references to any discussions (for example, other tickets or mailing list

adamjonas commented at 5:29 PM on May 26, 2020: member

A few grammatical comments and phrasing suggestions.

in CONTRIBUTING.md:85 in 336b300dc4 outdated

  81 | @@ -53,6 +82,8 @@ To contribute a patch, the workflow is as follows:
  82 |  The project coding conventions in the [developer notes](doc/developer-notes.md)
  83 |  must be followed.
  84 |  
  85 | +### Commiting Patches

jonatack commented at 5:38 PM on May 26, 2020:

Committing

in CONTRIBUTING.md:20 in 336b300dc4 outdated

  13 | @@ -14,15 +14,44 @@ purposes. As such there are repository "maintainers" who are responsible for
  14 |  merging pull requests as well as a "lead maintainer" who is responsible for the
  15 |  release cycle, overall merging, moderation and appointment of maintainers.
  16 |  
  17 | +Getting Started
  18 | +---------------
  19 | +
  20 | +New developers are very welcome and needed. There are a lot of open issues of

jonatack commented at 5:40 PM on May 26, 2020:

suggest s/a lot/many/

jonatack commented at 5:54 PM on May 26, 2020:

It may be a good idea to work in a phrase, similar to this one, early in this section:

Reviewing and testing is the most effective way you can contribute as a new contributor, and also will teach you much more about the code and process than opening PRs.

(credit to @jnewbery for that sentence: https://bitcoincore.reviews/16512#l-139)

jonatack commented at 5:54 PM on May 26, 2020: member

Concept ACK

hebasto commented at 6:06 PM on May 26, 2020: member

Concept ACK.

Empact commented at 6:37 PM on May 26, 2020: member

Concept ACK - perhaps address some of the linted spelling issues here? https://travis-ci.org/github/bitcoin/bitcoin/jobs/691399798

DrahtBot added the label Docs on May 26, 2020

fanquake commented at 10:41 AM on May 27, 2020: member

Looks good. Will ACK once you've taken suggestions (or not).

MarcoFalke force-pushed on May 27, 2020

MarcoFalke commented at 2:08 PM on May 27, 2020: member

Thanks @adamjonas, @jonatack and @Empact I may have addressed your feedback. Let me know if I forgot something

adamjonas commented at 2:15 PM on May 27, 2020: member

ACK fa42155

in CONTRIBUTING.md:31 in fa42155283 outdated

  26 | +
  27 | +Before you start contributing, familiarize yourself with the Bitcoin Core build
  28 | +system and tests. Refer to the documentation in the repository on how to build
  29 | +Bitcoin Core and how to run the unit and functional tests.
  30 | +
  31 | +There are many of open issues of varying difficulty waiting to be fixed.

jonatack commented at 3:47 PM on May 27, 2020:

s/many of/many/

in CONTRIBUTING.md:23 in fa42155283 outdated

  18 | +---------------
  19 | +
  20 | +New developers are very welcome and needed.
  21 | +
  22 | +Reviewing and testing is the most effective way you can contribute as a new
  23 | +contributor, and also will teach you much more about the code and process than

jonatack commented at 3:48 PM on May 27, 2020:

s/and/and it/

in CONTRIBUTING.md:152 in fa42155283 outdated

 147 | +
 148 |  Note that translations should not be submitted as pull requests. Please see
 149 |  [Translation Process](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md)
 150 |  for more information on helping with translations.
 151 |  
 152 | +### Work in Progress changes and Requests for Comment

jonatack commented at 3:50 PM on May 27, 2020:

s/Comment/Comments/ or Feedback (in singular form)

in CONTRIBUTING.md:20 in fa42155283 outdated

  13 | @@ -14,15 +14,49 @@ purposes. As such there are repository "maintainers" who are responsible for
  14 |  merging pull requests as well as a "lead maintainer" who is responsible for the
  15 |  release cycle, overall merging, moderation and appointment of maintainers.
  16 |  
  17 | +Getting Started
  18 | +---------------
  19 | +
  20 | +New developers are very welcome and needed.

jonatack commented at 3:53 PM on May 27, 2020:

s/developers/contributors/?

in CONTRIBUTING.md:24 in fa42155283 outdated

  19 | +
  20 | +New developers are very welcome and needed.
  21 | +
  22 | +Reviewing and testing is the most effective way you can contribute as a new
  23 | +contributor, and also will teach you much more about the code and process than
  24 | +opening PRs. Please refer to the section [peer review](#peer-review) later in

jonatack commented at 3:54 PM on May 27, 2020:

[Peer Review](#peer-review) (the section title markdown is ### Peer Review)

jonatack commented at 3:55 PM on May 27, 2020: member

A couple of grammar fixups but this is a nice improvement :heart:

in CONTRIBUTING.md:47 in fa42155283 outdated

  43 | +### Good First Issue Label
  44 | +
  45 | +The purpose of the `good first issue` label is to highlight which issues are
  46 | +suitable for a new contributor without a deep understanding of the codebase.
  47 | +
  48 | +However, `good first issue`s can be solved by anyone. If they remain unsolved

jonatack commented at 4:02 PM on May 27, 2020:

good first issues isn't very readable; suggest plain text here on line 47: good first issues (while leaving line 44 as it is)

doc: Fix unrelated typos reported by codespell fab893e0ca

MarcoFalke force-pushed on May 27, 2020

MarcoFalke commented at 4:41 PM on May 27, 2020: member

@jonatack Fixed

jonatack commented at 4:58 PM on May 27, 2020: member

ACK fa3981b3de1dd0d8bf04a93ab4c94af78231ec05

Sorry about the iterative review and the mistakes in my first review comments.

DrahtBot commented at 7:53 PM on May 27, 2020: member

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#19071 ([WIP RFC DONOTMERGE] meta: Separate repository for the gui by MarcoFalke)
#18027 ("PSBT Operations" dialog by gwillen)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

in CONTRIBUTING.md:70 in fa3981b3de outdated

  66 | @@ -33,7 +67,7 @@ requests.
  67 |  
  68 |  The developer
  69 |  [mailing list](https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev)
  70 | -should be used to discuss complicated or controversial changes before working on
  71 | +should be used to discuss complicated or controversial consensus or protocol changes before working on

laanwj commented at 3:53 PM on May 28, 2020:

maybe P2P protoocol? (to distinguish it from internal or interprocess interfaces)

MarcoFalke commented at 4:00 PM on May 28, 2020:

Done. Fixed in commit 100000d1

doc: Add headings to CONTRIBUTING.md

This makes it possible to link and refer to subsections

Also, minor clarifications

100000d1b2

doc: Expand section on Getting Started

Co-authored-by: Adam Jonas <jonas@chaincode.com>
Co-authored-by: Jon Atack <jon@atack.com>

fae2fb2a19

doc: Explain that anyone can work on good first issues, move text to CONTRIBUTING.md facef3d413

in .github/ISSUE_TEMPLATE/good_first_issue.md:17 in fa3981b3de outdated

  15 |  
  16 |  <!-- (For example, “C++11 std::thread”, “Qt5 GUI and async GUI design” or “basic understanding of Bitcoin mining and the Bitcoin Core RPC interface”.) -->
  17 |  
  18 |  #### Want to work on this issue?
  19 |  
  20 | -The purpose of the `good first issue` label is to highlight which issues are suitable for a new contributor without a deep understanding of the codebase.

laanwj commented at 3:54 PM on May 28, 2020:

I'm ~0 on removing this. You might want to replace it with a reference to the CONTRIBUTING.md.

MarcoFalke commented at 3:57 PM on May 28, 2020:

There should already be a link to CONTRIB.md

MarcoFalke force-pushed on May 28, 2020

MarcoFalke commented at 4:00 PM on May 28, 2020: member

Addressed feedback by @laanwj

hebasto approved

hebasto commented at 4:09 PM on May 28, 2020: member

ACK facef3d4131f9980a4516282f11731361559509c

fanquake approved

fanquake commented at 7:38 AM on June 1, 2020: member

ACK facef3d4131f9980a4516282f11731361559509c

fanquake merged this on Jun 1, 2020

fanquake closed this on Jun 1, 2020

MarcoFalke deleted the branch on Jun 1, 2020

sidhujag referenced this in commit 3d527f3eaa on Jun 1, 2020

DrahtBot locked this on Feb 15, 2022