GitLab

Attempt to make it more clear what expectations exists of both
contributors and maintainers, not to create new guidelines.

Includes a new section about critical code paths.

Reduce number of markdown lint errors by moving indented codeblocks to fenced codeblocks instead.
Notice in CONTRIBUTING.md and doc/developer-notes.md that the code in lists now render as intended in the mkdocs output.

Test-plan:

- Check out master
- `markdownlint -c .markdownlint.json -o /tmp/before CONTRIBUTING.md contrib/devtools/README.md contrib/seeds/README.md contrib/testgen/README.md doc/build-osx.md doc/build-unix.md doc/developer-notes.md doc/ninja_targets.md doc/unit-tests.md doc/gitian-building/gitian-building-create-vm-debian.md doc/gitian-building/gitian-building-manual.md`
- Check out this MR
- `markdownlint -c .markdownlint.json -o /tmp/after CONTRIBUTING.md contrib/devtools/README.md contrib/seeds/README.md contrib/testgen/README.md doc/build-osx.md doc/build-unix.md doc/developer-notes.md doc/ninja_targets.md doc/unit-tests.md doc/gitian-building/gitian-building-create-vm-debian.md doc/gitian-building/gitian-building-manual.md`
- Compare the `before` a...

Add angle brackets to bare URLs, and make some links not formatted as code.

Added a link to Chris Beam's article on good commit messages.
The tips given there should be general enough to satisfy our
requirements.

We do not strictly enforce things like commit message length,
formatting, content/metadata, most of our contributors generally
and naturally adhere to the advice given in this article.
And one can study the past project history to get a sense of
style.

Contributors should review the BCHN GitLab rules & guidelines,
they contain more specific info on commit tags used etc.

Test plan:
- review / read the doc / approve the info

Remove line-length warnings (MD013) from `/*.md`
(and one new line in `/doc/functional-tests.md`)

Test plan: (needs markdownlint v0.25.0 or later)
- `markdownlint -c .markdownlint.json -o /tmp/mdl.output *.md doc/*.md`
- `grep MD013 /tmp/mdl.output | egrep -v '(bips.md|bch-upgrades.md)'`

Output file (`/tmp/mdl.output`) should contain MD013 entries only for
`doc/bips.md` and `doc/bch-upgrades.md)`.
The above `grep` command should not output any lines.

Numbering was broken, starting over again and again, instead of going from 1 to 9.
This should make the ordered list in `CONTRIBUTING.md` render correctly with `mkdocs`.

Test plan
---------

Make sure you have `mkdocs` and `mkdocs-material` installed (`pip install mkdocs` and `pip install mkdocs-material` - adjust per your installation / distribution)

Go to your working area root folder, and run the doc deployment prep commands from `.gitlab-ci.yml`:

```
mkdir files-for-mkdocs
(cd files-for-mkdocs ; ln -s ../* . ; rm -rf files-for-mkdocs)
rm -f files-for-mkdocs/{depends,src}
tar cf - $(find src depends -name \*.md) | ( cd files-for-mkdocs ; tar xf - )
tar cf - src/chainparams.cpp src/crypto/sha256_sse4.cpp src/interfaces/*.h src/qt/intro.cpp src/univalue/COPYING | ( cd files-for-mkdocs ; tar xf - )
rm -f files-for-mkdocs/doc/release-notes.md
mkdocs build
```

Then run `mkdocs serve` and browse to http://127.0.0.1:8000
to take a look at the rendered document (and compare to previous
version using the same doc building procedure on `master` before this change)

Also contains some ABC->BCHN updating in
doc/gitian-building/gitian-building-manual.md.

- Change git alias `mr` so it doesn't conflict with existing use (see commit for details).
- Update repo location for qa-assets.
- Note about missing `test-runner.py` when fuzzing.

Test plan: review

Includes some trailing whitespace removals in documents.

Test plan:

- review document changes
- run `gitian-build.py -h`, verify 'GitLab' spelling in -R option help

Closes #66

Summary:
This diff enables running `clang-tidy` at build time.

The checks are defined in the `src/.clang-tidy` file, and apply to every
subdirectories as well. For now, a single check is enabled to replace
`boost::lexical_cast<std::string>` with `std::to_string` (see
https://releases.llvm.org/8.0.0/tools/clang/tools/extra/docs/clang-tidy/checks/boost-use-to-string.html).
This check should never trigger since D5136 removes
`boost::lexical_cast`, and our libraries are not using boost.

Depends on D5136.

Test Plan:
Pre-requisite: with no clang-tidy installed:
  cmake -GNinja ..
Check that cmake returns an error because it fails to find `clang-tidy`.
  cmake -GNinja .. -DENABLE_CLANG_TIDY=OFF
  ninja
Should return no error.

Install `clang-tidy` version >= 8.
  cmake -GNinja ..
  ninja check-all bitcoin-bench

Add a `boost::lexical_cast<std::string>` case in any bitcoin-abc source
file, then run `ninja` again. Check that clang-tidy applied the fix and
replaced it with `std::to_string`.
Note: it seems that clang-tidy does not always replace, but sometimes
only outputs the warning.

Reviewers: #bitcoin_abc, deadalnix

Reviewed By: #bitcoin_abc, deadalnix

Differential Revision: https://reviews.bitcoinabc.org/D5138

Summary: Added the command that allowed me to use clang-format-8 without having to recompile llvm & clang to CONTRIBUTING.md.

Test Plan: I ran `npm install -g clang-format@1.2.4`. I had to delete/move some files due to conflicts with another installation, but after that, running `arc diff` succeeded. A fresh installation should work with just that command; otherwise the instructions can be amended to accomodate for additional problems.

Reviewers: deadalnix, O1 Bitcoin ABC, #bitcoin_abc, Fabien

Reviewed By: O1 Bitcoin ABC, #bitcoin_abc, Fabien

Subscribers: Fabien

Differential Revision: https://reviews.bitcoinabc.org/D4862

Summary: Adds another relevant link to CONTRIBUTING.md

Test Plan: Check the link, make sure it works

Reviewers: deadalnix, #bitcoin_abc, Fabien

Reviewed By: #bitcoin_abc, Fabien

Subscribers: Fabien

Differential Revision: https://reviews.bitcoinabc.org/D4847

Summary:
Includes some fixes and refreshes here and there.
All these instructions have been tested working on the following
platforms:
 - FreeBSD 12.0
 - MacOS Catalina 10.15.1
 - Ubuntu Bionic 18.04 (WSL)
 - Debian Buster (10)
 - Fedora 31

Test Plan: Read the documents, follow the instructions and check it works !

Reviewers: #bitcoin_abc, deadalnix, jasonbcox

Reviewed By: #bitcoin_abc, jasonbcox

Subscribers: jasonbcox

Differential Revision: https://reviews.bitcoinabc.org/D4748

Summary: fix outdated mention of clang-format-7

Test Plan: note that arc lint fails unless clang-format-8 is installed, even if clang-format-7 is available

Reviewers: O1 Bitcoin ABC, #bitcoin_abc, deadalnix, jasonbcox, Mengerian

Reviewed By: O1 Bitcoin ABC, #bitcoin_abc, jasonbcox, Mengerian

Subscribers: Mengerian

Differential Revision: https://reviews.bitcoinabc.org/D4634

Summary:
This fixes the error message that mistakenly request `clang-format`
version 7.x while D4539 introduced version >= 8.x.

Also update the doc as suggested in D4539.

Test Plan:
  arc lint --everything
Read the doc.

Reviewers: #bitcoin_abc, deadalnix, Mengerian

Reviewed By: #bitcoin_abc, Mengerian

Subscribers: Mengerian

Differential Revision: https://reviews.bitcoinabc.org/D4551

Summary: https://github.com/Bitcoin-ABC/bitcoin-abc/pull/359

Test Plan: I'm not aware of a way to test this beyond reading it.

Reviewers: #bitcoin_abc, deadalnix

Reviewed By: #bitcoin_abc, deadalnix

Differential Revision: https://reviews.bitcoinabc.org/D4543

Summary:
Adapted to run as an Arcanist linter, and added fixes for the scripts
which are Bitcoin ABC only.

Because the quantity of shell script is limited, the performance cost is
almost unnoticeable.

Backport of core PR12871
https://github.com/bitcoin/bitcoin/pull/12871/files

Depends on D3956, D3957 and D3958.

Test Plan:
Should return no error:
  arc lint --everything

Add an unsused variable in a script and lint that file:
  arc lint -- <the_script_file>
Check the linter returns a warning.

Reviewers: #bitcoin_abc, deadalnix

Reviewed By: #bitcoin_abc, deadalnix

Differential Revision: https://reviews.bitcoinabc.org/D3959

Summary: As per title.

Test Plan: Read the doc.

Reviewers: #bitcoin_abc, deadalnix

Reviewed By: #bitcoin_abc, deadalnix

Differential Revision: https://reviews.bitcoinabc.org/D3737

Summary:
While setting up my new computer today I noticed that clang-format-7
is conveniently available in recent Ubuntus, and the recent Debian too.

https://packages.ubuntu.com/search?keywords=clang-format-7
https://packages.debian.org/search?keywords=clang-format-7

Also, I've taken the liberty to add a small note explaining *why* these tools
are needed.

Test Plan: read

Reviewers: deadalnix, Fabien, #bitcoin_abc

Reviewed By: deadalnix, #bitcoin_abc

Differential Revision: https://reviews.bitcoinabc.org/D3672

Summary:
This is a backport of core PR11003.
Due to documentation divergence, it has been extended to the whole
`doc/` directory (excluding archived release notes) as well as
`contrib/`.
https://github.com/bitcoin/bitcoin/pull/11003/files

Test Plan: Read the docs.

Reviewers: #bitcoin_abc, deadalnix, jasonbcox

Reviewed By: #bitcoin_abc, jasonbcox

Differential Revision: https://reviews.bitcoinabc.org/D3401

Summary: As per title.

Test Plan:
  make check
  ./test/functional/test_runner.py

Reviewers: #bitcoin_abc, deadalnix

Reviewed By: #bitcoin_abc, deadalnix

Differential Revision: https://reviews.bitcoinabc.org/D3216

Summary:
Although the article may be useful as general advice, it seems out of place with the other articles.
It's better to keep these articles focused on specific development-style information that people may not easily find elsewhere.

Test Plan: N/A

Reviewers: deadalnix, #bitcoin_abc

Reviewed By: deadalnix, #bitcoin_abc

Subscribers: schancel

Differential Revision: https://reviews.bitcoinabc.org/D2781

Summary:
Add two more articles about good development practices
that we want to encourage for Bitcoin ABC

Test Plan: Check the links and read the articles

Reviewers: deadalnix, #bitcoin_abc

Reviewed By: deadalnix, #bitcoin_abc

Subscribers: schancel

Differential Revision: https://reviews.bitcoinabc.org/D2780

Summary:
Both florian and I were late to the ccache thing and when we finally
started using it, we were very pleased with the results. For new contibutors
this is a helpful tip.

Test Plan: none

Reviewers: #bitcoin_abc, deadalnix, Mengerian

Reviewed By: #bitcoin_abc, Mengerian

Subscribers: Mengerian, teamcity, schancel

Differential Revision: https://reviews.bitcoinabc.org/D2554

Summary:
Using flake8 code F401, unused imports are output as lint errors from
acanist.
flake8 is preferred here over pylint because it offers more feature for
the long-term improvement. It could also throw pep8 errors but will not
fix them like autopep8 does, so better use both.

Based on core PR11835

Depends on D2445, D2446, D2447, D2448, D2449, D2450

Test Plan:
Add an unused import in a py file and run `arc lint`. An error should be
reported
Read the CONTRIBUTING.md doc

Reviewers: #bitcoin_abc, deadalnix, jasonbcox

Reviewed By: #bitcoin_abc, jasonbcox

Subscribers: teamcity, schancel

Differential Revision: https://reviews.bitcoinabc.org/D2451

Summary: Also add apt package link

Test Plan: I used the apt.llvm.org source to install clang-7 in Ubuntu, and it worked.

Reviewers: Fabien, deadalnix, jasonbcox, #bitcoin_abc

Reviewed By: deadalnix, #bitcoin_abc

Subscribers: markblundeberg, teamcity, schancel

Differential Revision: https://reviews.bitcoinabc.org/D2343

Summary:
Point to the backporting.md document if people are looking
for something to work on.

Test Plan: Read it

Reviewers: deadalnix, jasonbcox, #bitcoin_abc

Reviewed By: deadalnix, jasonbcox, #bitcoin_abc

Subscribers: teamcity, schancel

Differential Revision: https://reviews.bitcoinabc.org/D2183

Summary: It is pretty much unused, so it's confusing to send new people there.

Test Plan: N/A

Reviewers: Fabien, jasonbcox, deadalnix, #bitcoin_abc

Reviewed By: deadalnix, #bitcoin_abc

Subscribers: teamcity, schancel

Differential Revision: https://reviews.bitcoinabc.org/D2182

Summary: Remove inline code quotes, which make the links non-clickable in Github.

Test Plan: N/A

Reviewers: jasonbcox, Fabien, #bitcoin_abc, deadalnix

Reviewed By: #bitcoin_abc, deadalnix

Subscribers: teamcity, schancel

Differential Revision: https://reviews.bitcoinabc.org/D2178

Summary: Per title.

Test Plan: Click the link and read it.

Reviewers: #bitcoin_abc, jasonbcox

Reviewed By: #bitcoin_abc, jasonbcox

Subscribers: teamcity

Differential Revision: https://reviews.bitcoinabc.org/D2129

Summary: Feedback from https://github.com/Bitcoin-ABC/bitcoinabc.org/pull/24 indicated the disclosure policy should be part of the repo itself.  I totally agree.

Test Plan:
1. Read it carefully.
2. Try it out yourself.

Reviewers: deadalnix, schancel, Fabien, Mengerian, #bitcoin_abc

Reviewed By: deadalnix, Fabien, #bitcoin_abc

Subscribers: teamcity

Differential Revision: https://reviews.bitcoinabc.org/D1993

Summary: autopep8 is not intuitive to install for devs not familiar with it and/or pip.

Test Plan: Installed using this method.

Reviewers: deadalnix, schancel, #bitcoin_abc

Reviewed By: deadalnix, #bitcoin_abc

Subscribers: teamcity

Differential Revision: https://reviews.bitcoinabc.org/D1585

Summary: Markdown link had the wrong kind of brackets. This fixes them.

Test Plan: Check that the link displays properly in Markdown viewer

Reviewers: deadalnix, schancel, jasonbcox, #bitcoin_abc

Reviewed By: deadalnix, #bitcoin_abc

Subscribers: teamcity

Differential Revision: https://reviews.bitcoinabc.org/D1475

Summary: As per title.

Test Plan: Read the documentatino

Reviewers: deadalnix, jasonbcox, mbhinder, jimpo, matiu, Mengerian, #bitcoin_abc

Reviewed By: jasonbcox, jimpo, #bitcoin_abc

Subscribers: teamcity

Differential Revision: https://reviews.bitcoinabc.org/D1298

Summary:
Based on Amaury's comments in Dev Slack channel
Explain that development process prioritizes fixing bugs when found, above other tasks

Test Plan: Amaury should check that the wording reflects how he wants the process to work

Reviewers: deadalnix, schancel, jasonbcox, #bitcoin_abc

Reviewed By: jasonbcox, #bitcoin_abc

Subscribers: teamcity

Differential Revision: https://reviews.bitcoinabc.org/D1294

Summary: amend changes to a accepted diff is dangerous, which will make the codebase out of control.

Test Plan: NA

Reviewers: #bitcoin_abc, O1 Bitcoin ABC, schancel

Reviewed By: #bitcoin_abc, O1 Bitcoin ABC, schancel

Subscribers: teamcity

Differential Revision: https://reviews.bitcoinabc.org/D1270

Make the docs more clear that setting your git remote origin is necessary for Arcanist to work properly

Summary:
New users tend to encounter this when they clone from github.  While we did improve the CONTRIBUTING.md docs, it could be more clear that
setting the remote is necessary for Arcanist to work properly.

Test Plan: N/A

Reviewers: schancel, movrcx, #bitcoin_abc

Reviewed By: schancel, #bitcoin_abc

Subscribers: teamcity

Differential Revision: https://reviews.bitcoinabc.org/D1195

Summary: Add a second about why we exist.

Test Plan: Read it

Reviewers: deadalnix, jasonbcox, Mengerian, #bitcoin_abc

Reviewed By: deadalnix, jasonbcox, Mengerian, #bitcoin_abc

Subscribers: teamcity

Differential Revision: https://reviews.bitcoinabc.org/D1115