Skip to content

Commit

Permalink
[electrum] initial monorepo integration
Browse files Browse the repository at this point in the history 
Summary:
This is a copy of the ElectrumABC repository as of commit 9b72b3e

Two files related to CI and linting have been removed: `.pre-commit-config.yaml` and `.cirrus.yml`.
A new configuration file `.isort.cfg` has been added to mark the main packages as know first party packages to prevent `isort` from sorting them as third-party packages.

Permanent linter settings:

- The main modules are excluded from `lint-python-shebang` as a shebang does not make sense for non-scripts.
- Auto-generated files (protobuf and icons.py) are excluded from linters.

Temporary linter exclusions (to be fixed in separate diffs):

- `flake8`, because of remaining warnings from flake8 plugins (A001, A002, C401...)
- `lint-python-encoding`
- `shellcheck`
- `flynt` (low priority)
- `mypy` (low priority and difficult to fix)

Linter related changes:
- corrected spelling
- corrected and added bash shebangs
- added `export LC_ALL=C.UTF-8` to shell

Other changes:
- adapted the build scripts to work when the directory mapped to ELECTRUM_ROOT inside the docker is not the root of a git repo

Test Plan:
`arc lint --everything`

Make sure Electrum ABC works: `cd electrum && ./electrum-abc`

Check the `Help > Report Bug` menu now points to the Bitcoin-ABC repo

Make sure the build toolchains work:
```
cd electrum
contrib/build-wine/build.sh
contrib/build-linux/appimage/build.sh
contrib/build-linux/srcdist-docker/build.sh
```

Reviewers: #bitcoin_abc, Fabien

Reviewed By: #bitcoin_abc, Fabien

Subscribers: Fabien

Differential Revision: https://reviews.bitcoinabc.org/D14088
  • Loading branch information
@PiRK
PiRK authored and abc-bot committed Jul 20, 2023
1 parent e167f3b commit 757344c
Show file tree
Hide file tree
Showing 100 changed files with 2,538 additions and 823 deletions.
290 changes: 143 additions & 147 deletions CONTRIBUTING.md
View file
@@ -1,201 +1,197 @@
# Contributing to Electrum ABC

## Main repository
The Electrum ABC project welcomes contributors!

The Electrum ABC source repository has been merged into the Bitcoin ABC repository,
and the development is now taking place at [reviews.bitcoinabc.org](https://reviews.bitcoinabc.org/).
This guide is intended to help developers and non-developers contribute effectively to the project.

Please read the main [CONTRIBUTING.md](https://github.com/Bitcoin-ABC/bitcoin-abc/blob/master/CONTRIBUTING.md)
document to familiarize yourself with the development philosophy and find out how to
set up the Bitcoin ABC repository.
The development philosophy and communication channels are identical to the ones
used by the Bitcoin-ABC project. Please read the relevant sections in
[Bitcoin ABC's CONTRIBUTING.md document](https://github.com/Bitcoin-ABC/bitcoin-abc/blob/master/CONTRIBUTING.md).

The original Electrum ABC github repository is maintained as a mirror of the `electrum/`
directory in the main repository.
The rest of this document provides information that is specific to
Electrum ABC.

The rest of this document provides instructions that are specific to Electrum ABC.
## Contributing to the development

## Contacting developers
### Getting set up with the Electrum ABC Repository

[Join the Electrum ABC telegram group](https://t.me/ElectrumABC) to get in contact
with developers or to get help from the community.
Electrum ABC is hosted on Github.com. To contribute to the repository,
you should start by creating an account on github.com.

## Installing dependencies
You will then need to clone the main repository. For that, navigate to
https://github.com/bitcoin-abc/ElectrumABC, and click the *Fork* button
that is on the top right of the window. This will create a new github
repository that is under your own management.

All commands in this document assume that your current working directory is the
`electrum/` directory that resides at the root of the Bitcoin ABC repository.
If your Github username is *your_username*, you will now have a copy of
the Electrum ABC repository at the address
`https://github.com/your_username/ElectrumABC`

### Python
Next, you must clone your github repository on your own computer,
so that you can actually edit the files. The simplest way
of doing this is to use the HTTPS link of your remote repository:

Python 3.7 or above is required to run Electrum ABC.
```shell
git clone https://github.com/your_username/ElectrumABC.git
```

If your system lacks Python 3.7+, you can use `pyenv` to install newer versions, or
install an [alternative python distribution](https://www.python.org/download/alternatives/)
in addition to your system's version.
This has the drawback of requiring you to type your password every time
you want to use a git command to interact with your remote repository.
To avoid this, you can also connect to GitHub with SSH. This is a bit more
complicated to set up initially, but will save you time on the long run.
You can read more on this subject here:
[Connecting to GitHub with SSH](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh)

### Python packages
Now you should have a local directory named `ElectrumABC`, with a single
remote repository named `origin`. This remote was set up automatically by
the git clone command. You can check this using the `git remote -v` command.

The simplest way to install all needed packages is to run the following command:
```shell
pip install .[all]
$ cd ElectrumABC
$ git remote -v
origin git@github.com:your_username/ElectrumABC.git (fetch)
origin git@github.com:your_username/ElectrumABC.git (push)
```

This will install Electrum ABC and all its dependencies as a python package and application.
The next step is to also add the main repository to the available
remote repositories. Call it `upstream`.

This is equivalent to:
```shell
pip install .
pip install .[gui]
pip install .[hardware]
$ git remote add upstream https://github.com/Bitcoin-ABC/ElectrumABC.git
$ git remote -v
origin git@github.com:your_username/ElectrumABC.git (fetch)
origin git@github.com:your_username/ElectrumABC.git (push)
upstream https://github.com/Bitcoin-ABC/ElectrumABC.git (fetch)
upstream https://github.com/Bitcoin-ABC/ElectrumABC.git (push)
```

If you do not want to install Electrum ABC as a package, you can install only the dependencies
using the following commands:
```shell
pip3 install -r contrib/requirements/requirements.txt
pip3 install -r contrib/requirements/requirements-binaries.txt
pip3 install -r contrib/requirements/requirements-hw.txt
```
Before writing or editing code, you must set-up pre-commit hooks to enforce
a consistent code style.
This is done by installing the [`pre-commit` tool](https://pre-commit.com/), and
then running `pre-commit install` in the root directory of the project.

## Running Electrum ABC from source

If you installed the application as a python package, you can run it from anywhere
using `electrum-abc` (assuming that your system has the python script directory in
its PATH).

If you installed all dependencies, you can also start the application by invoking
the `./electrum-abc` script. See the following sections for additional instructions
and optional dependencies.

### Running from source on old Linux

If your Linux distribution has a version of python 3 lower than the minimum required
version, it is recommended to do a user dir install with
[pyenv](https://github.com/pyenv/pyenv-installer). This allows Electrum ABC
to run completely independently of your system configuration.

1. Install `pyenv` in your user
account. Follow the printed instructions about updating your environment
variables and `.bashrc`, and restart your shell to ensure that they are
loaded.
2. Run `pyenv install 3.9.7`. This will download and compile that version of
python, storing it under `.pyenv` in your home directory.
3. `cd` into the Electrum ABC directory. Run `pyenv local 3.9.7` which inserts
a file `.python-version` into the current directory.
4. [Install Electrum ABC requirements](#python-packages)
5. [Compile libsecp256k1](#compiling-libsecp256k1)

### Running from source on macOS

You need to install **either** [MacPorts](https://www.macports.org) **or**
[HomeBrew](https://www.brew.sh). Follow the instructions on either site for
installing (Xcode from [Apple's developer site](https://developer.apple.com)
is required for either).

1. After installing either HomeBrew or MacPorts, clone this repository and
switch to the directory:
`git clone https://github.com/Bitcoin-ABC/ElectrumABC && cd ElectrumABC`
2. Install python 3.7+. For brew:
`brew install python3`
or if using MacPorts:
`sudo port install python37`
3. Install PyQt5: `python3 -m pip install --user pyqt5`
4. [Install Electrum ABC requirements](#python-packages)
5. [Compile libsecp256k1](#compiling-libsecp256k1)

## Running tests

Running unit tests:
```shell
python3 test_runner.py
pip install pre-commit
pre-commit install
```

This can also be run as a `ninja` target in the context of a Bitcoin ABC build:
You are now ready to contribute to Electrum ABC.

### Development workflow

This section is a summary of a typical development workflow. It assumes that
you are already familiar with *git*. If you aren't, start by reading a tutorial
on that topic, for instance:
[Starting with an Existing Project | Learn Version Control with Git](https://www.git-tower.com/learn/git/ebook/en/command-line/basics/working-on-your-project/#start)

After the initial set up, your local repository should be in the same
state as the main repository. However, the remote repository will change
as other people contribute code. So before you start working on any
development, be sure to synchronize your local `master` branch with `upstream`.

```shell
ninja check-electrum
git checkout master
git pull upstream master
```

Functional tests can be run with the following command:
Now, create a local development branch with a descriptive name. For instance,
if you want to fix a typo in the `README` file, you could call it
`readme_typo_1`

```shell
pytest electrumabc/tests/regtest
git checkout -b readme_typo_1
```

This requires `docker` and additional python dependencies:
The next step is to edit the source files in your local repository and
commit the changes as you go. It is advised to test your changes after
each commit, and to add a *test plan* in your commit message.
Each new commit should be strictly an improvement, and should not break
any existing feature. When you are finished, push your
branch to your own remote repository:

```shell
pip3 install -r contrib/requirements/requirements-regtest.txt
git push origin readme_typo_1
```

## Compiling libsecp256k1
Now go to GitHub. The new branch will show up with a green Pull Request button.
Make sure the title and message are clear, concise, and self-explanatory.
Then click the button to submit it. Your pull request will be reviewed by
other contributors.

Compiling libsecp256k1 is highly-recommended when running from source, to use fast
cryptographic algorithms instead of using fallback pure-python algos.
Address the reviewer's feedback by editing the local commits and pushing them
again to your repository with `git push -f`. Editing a past commit requires
more advanced git skills. See
[Rewriting history](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase).
If you don't feel confident enough to do this, you can fix the code by adding new
commits and the reviewer can take care of rebasing the changes.
But we encourage you to try first, and feel free to ask for help.

It is required when using CashFusion, as slow participants can cause a fusion round
to fail.
GitHub will automatically show your new changes in the pull request after you push
them to your remote repository, but the reviewer might not be aware of the changes.
So you should post a reply in the pull request's *Conversation* to notify him of
the changes.

On Debian or Ubuntu linux:
```shell
sudo apt-get install libtool automake
./contrib/make_secp
```
### General guidelines

On MacOS:
```shell
brew install coreutils automake
./contrib/make_secp
```
Electrum ABC adheres to standard Python style guidelines and good practices.
To ensure that your contributions respect those common guidelines, it is
recommended to use a recent IDE that includes a linter, such as PyCharm
or Sublime Text with the SublimeLinter plugin, and to not ignore any
codestyle violation warning.

or if using MacPorts: `sudo port install coreutils automake`
Alternatively, you can manually run a linter on your code such as
[`flake8`](https://pypi.org/project/flake8/).

## Compiling the icons file for Qt
The initial codebase does not strictly adhere to style guidelines, and we do
not plan to immediately fix this problem for the entire codebase, as this would
make backports from Electron Cash harder. But any new code, or existing code
that is modified, should be fixed.

If you change or add any icons to the `icons` subdirectory, you need to run the following
script before you can use them in the application:
```shell
contrib/gen_icons.sh
```
Automatic formatting is achieved using pre-commit hooks that run the following
formatting tools:
- [`isort`](https://pycqa.github.io/isort/)
- [`black`](https://github.com/psf/black)

This requires the `pyrcc5` command which can be installed using your package manager.
For instance for Ubuntu or Debian, run:
```
sudo apt-get install pyqt5-dev-tools
```
The code should be documented and tested.

## Creating translations
<!-- FIXME: we are still relying on Electron Cash translations-->
```shell
sudo apt-get install python-requests gettext
./contrib/make_locale
```
## Other ways of contributing

## Plugin development
In addition to submitting pull requests to improve the software or its documentation,
there are a few other ways you can help.

For plugin development, see the [plugin documentation](electrumabc_plugins/README.md).
### Running an Electrum server

## Creating Binaries
Electrum ABC relies on a network of SPV servers. If you can run a full node and
a public Electrum server, this will improve the resiliency of the network by
providing on more server for redundancy.

See the *Building the release files* section in [contrib/release.md](contrib/release.md)
You will need to keep your node software updated, especially around hard fork dates.

## Backporting
If you run a such an Electrum server, you can contact us to have it added
to the [list of trusted servers](electrumabc/servers.json), or submit
a pull request to add it yourself. You can run such a server for the mainnet
or for the [testnet](electrumabc/servers.json).

Electrum or Electron Cash features, refactoring commits or bug fixes can be
backported into Electrum ABC.
See https://github.com/cculianu/Fulcrum for how to run a SPV server.

To do this, first add the remote repositories:
```shell
git remote add electrum https://github.com/spesmilo/electrum.git
git remote add electroncash https://github.com/Electron-Cash/Electron-Cash.git
```
### Translations

Then fetch the remote git history:
```shell
git fetch electrum
git fetch electroncash
```
The messages displayed in the graphical interface need to be translated in
as many languages as possible. At the moment, Electrum ABC is still using the
[Electron Cash translations](https://crowdin.com/project/electron-cash) from
the date of the fork. As the Electrum ABC graphical interface will slowly
diverge from Electron Cash, we will need to update the translations
accordingly.

This step must be repeated every time you want to backport a commit that is more
recent than the last time you fetched the history.
If you are interested in helping to set up and manage a separate translation
project for Electrum ABC, feel free to contact us on github.

Then you can cherry-pick the relevant commits:
```shell
git cherry-pick -Xsubtree=electrum <commit hash>
```
### Reviewing pull requests

Contributing code is great, but all new code must also be reviewed before being
added to the repository. The review process can be a bottleneck, when other
contributors are very busy. Feel free to review any open pull request, as
having multiple reviewers increase the chances of spotting bugs before they
can cause any damage.

See [Linus's law](https://en.wikipedia.org/wiki/Linus%27s_law).
2 changes: 1 addition & 1 deletion MANIFEST.in
View file
Expand Up @@ -2,7 +2,7 @@
# but for now we keep it to avoid hacks such as copying the file in
# contrib/make_linux_sdist
include LICENCE RELEASE-NOTES.md AUTHORS
include README.md
include README.rst
include electrum-abc.desktop
include *.py
include electrum-abc
Expand Down

0 comments on commit 757344c

Please sign in to comment.