This discussion is forked from Reputation. The following is subject to further expansion and amendment. In accord with the local rules, suggestions are welcome! I especially want to expand this from its Github specificity; I myself actually dislike Github, but some of the stuff here is rather Github specific.Reader-writer priority issue: I think that this topic will attract better advice in the technical forum, but may arguably be oriented toward readers in Beginners & Help. Its subject matter seems borderline: Newbie-level Github usage. Should I move it?
I don’t want to scare you off with a learning curve; and I would not suggest that you should take the time and effort of learning
all of the below for
only one contribution. But since you care about open-source software,
contributing on Github is a generally useful skill. Whether or not you code, you may wish to contribute translations, documentation, and also, well-made bug reports that help developers. Learning this
once will open a whole new world to you!
Nine [9] tips for Github newbies:
0.Github has detailed help pages. Use them, especially this: “
Collaborating with issues and pull requests”.
1.Open an
issue concisely describing the problem, and (if applicable) noting that you will offer a solution. Avoid discussion of the personalities involved, unless it is necessary. Well-run Github projects are meritocracies; competent maintainers try to avoid drama. If someone else tries to raise drama, take the high road—unless it turns out that the maintainers are total idiots, in which case the project will probably fail anyway unless it has big corporate backers.
I don’t want to sound negative. It’s just that Github newbies oftentimes don’t realize that every comment on every issue gets spammed to a whole bunch of busy people, most of whom are interested only in project management. They definitely appreciate comments that help with project management! If you wonder why many Bitcoin Core developers have forum accounts that have been inactive for years, or are barely, rarely active, this probably explains why. :-(
A good tip offered downthread:...if you are contributing to a different project (bitcoin related or not) check and see if there is a preferred format of submitting an issue. [...]
Not saying one way is better then another but if the project has a way they want it, please use their format.
2.In the ensuing discussion, if you simply agree or disagree with a comment without substantive reply, feel free to use the little emoji buttons to express thumbs-up, thumbs-down, heart, “confused”, “party”, etc. Again, Github issues are a place for practical project management, not a forum;
usually, excessively verbose discussion should be avoided. Of course, if you have a substantive remark that will help project maintainers, don’t be shy about expressing it!
3.Issue and pull request comments use
Markdown for formatting; Github uses
CommonMark, with
“GitHub Flavored Markdown” extensions. There is a
Github Guide for this.
At-mentions work (
@username).
There are also some tricks for cross-references,
e.g. #1234 would automagically link to issue or PR #1234 in the same repository, with a backlink;
bitcoin/bitcoin#19953 would link to/backlink from
the PR merging Schnorr/Taproot consensus rules into Bitcoin; and
bitcoin/bitcoin@8bbed4b (the first seven hexadecimal digits of the commit hash) would reference
the commit implementing Taproot validation.
(Please don’t spam that PR and commit with references from irrelevant issues!)
4.Make a
fork of the main repository, make a
branch within your fork, and
commit your work to the branch. Read the pull request documentation to understand why.
5.If you wish to request several distinct actions, make
atomic commits to your branch. For example, if you wish to delete the bad translation and add the good translation, make those actions into two separate git commits which can “upstreamed” together in one pull request, as I will briefly describe below.
6.Learn
“How to Write a Git Commit Message”. Don’t overdo it; just follow the guidelines. Using the customary style for commit messages shows professionalism, and it really does make things easier for the people who will read the commit log in the future.
“
The Seven Rules” are not arbitrary, as you will understand if you ever accrue experience reading commit logs:
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
commit logs are
exemplary, albeit probably incomprehensible to non-coders. On the flipside, I can “smell” a bad project by the odour of sloppy commit logs.
7.If you want to secure your commits,
add a PGP key to your Github profile before you commit anything, and sign your commits. This is an
absolute requirement for security-critical code;
n.b. that
all of Bitcoin Core’s commits show “Verified” status. It arguably
may be less important for a whitepaper translation; but if you really want to do things right, invest some time to learn a process that will be fast and easy thereafter.
N.b. that you cannot go back and retroactively secure commits that were made without digital signatures.If I were to manage a public repository of any kind,
all substantive commits would require signatures as a matter of policy. Unfortunately, most repositories do not have such a policy.
8.File a
pull request (PR). This is the action that asks the project maintainers to
merge your repository’s branch’s commits into
(typically) the project’s “master” branch.
In your pull request, reference the
issue that you raised with specific language that Github recognizes automagically. For example, if you raised Issue #1234, then say your pull request’s text,
Closes #1234. or
Fixes #1234. This way, the issue is automagically hyperlinked bidirectionally; and if your PR is accepted, the Github system will close your issue with an appropriate note and cross-reference.
Good luck!
Local rules: Some people are categorically banned from all of my threads. You know who you are. Don’t try it here.
Others will be moderated at my sound discretion.
