41fc11fa Scheduled mandatory software upgrades (xmr-eric)
3b5382fe Keep VRP a proper noun (xmr-eric)
7160cbd6 CONTRIBUTING.md capitalization (xmr-eric)
f36ffc07 Shorten a title, remove a section, small edits (xmr-eric)
00179917 Capitalization on first word only (xmr-eric)
6ffae079 Readme.md: Normalize heading capitalization (xmr-eric)
@ -6,13 +6,13 @@ if you want to help that way. Testing is invaluable in making a piece
of software solid and usable.
## General Guidelines
## General guidelines
* Comments are encouraged.
* If modifying code for which Doxygen headers exist, that header must be modified to match.
* Tests would be nice to have if you're adding functionality.
Patches are preferably to be sent via a github pull request. If that
Patches are preferably to be sent via a Github pull request. If that
can't be done, patches in "git format-patch" format can be sent
(eg, posted to fpaste.org with a long enough timeout and a link
posted to #monero-dev on irc.freenode.net).
@ -21,7 +21,7 @@ Patches should be self contained. A good rule of thumb is to have
one patch per separate issue, feature, or logical change. Also, no
other changes, such as random whitespace changes or reindentation.
Following the code style of the particular chunk of code you're
modifying is encourgaged. Proper squashing should be done (eg, if
modifying is encouraged. Proper squashing should be done (eg, if
you're making a buggy patch, then a later patch to fix the bug,
both patches should be merged).
@ -36,13 +36,13 @@ for commit. As you add hunks with git add -p, those hunks will
"move" from the git diff output to the git diff --cached output,
so you can see clearly what your commit is going to look like.
## Commits and Pull Requests
## Commits and pull requests
Commit messages should be sensible. That means a subject line that
describes the patch, with an optional longer body that gives details,
documentation, etc.
When submitting a pull request on github, make sure your branch is
When submitting a pull request on Github, make sure your branch is
rebased. No merge commits nor stray commits from other people in
your submitted branch, please. You may be asked to rebase if there
are conflicts (even trivially resolvable ones).
@ -100,7 +100,7 @@ C4 is meant to provide a reusable optimal collaboration model for open source so
- Maintainers SHALL have commit access to the repository.
- Everyone, without distinction or discrimination, SHALL have an equal right to become a Contributor under the terms of this contract.
### Licensing and Ownership
### Licensing and ownership
- The project SHALL use a share-alike license, such as BSD-3, the GPLv3 or a variant thereof (LGPL, AGPL), or the MPLv2.
- All contributions to the project source code ("patches") SHALL use the same license as the project.
@ -108,7 +108,7 @@ C4 is meant to provide a reusable optimal collaboration model for open source so
- The copyrights in the project SHALL be owned collectively by all its Contributors.
- Each Contributor SHALL be responsible for identifying themselves in the project Contributor list.
### Patch Requirements
### Patch requirements
- Maintainers MUST have a Platform account and SHOULD use their real names or a well-known alias.
- Contributors SHOULD have a Platform account and MAY use their real names or a well-known alias.
@ -120,7 +120,7 @@ C4 is meant to provide a reusable optimal collaboration model for open source so
- A patch commit message SHOULD consist of a single short (less than 50 character) line summarizing the change, optionally followed by a blank line and then a more thorough description.
- A "Correct Patch" is one that satisfies the above requirements.
### Development Process
### Development process
- Change on the project SHALL be governed by the pattern of accurately identifying problems and applying minimal, accurate solutions to these problems.
- To request changes, a user SHOULD log an issue on the project Platform issue tracker.
@ -143,7 +143,7 @@ C4 is meant to provide a reusable optimal collaboration model for open source so
- Any Contributor who has value judgments on a correct patch SHOULD express these via their own patches.
- Maintainers MAY commit changes to non-source documentation directly to the project.
### Creating Stable Releases
### Creating stable releases
- The project SHALL have one branch ("master") that always holds the latest in-progress version and SHOULD always build.
- The project SHALL NOT use topic branches for any reason. Personal forks MAY use topic branches.
@ -151,7 +151,7 @@ C4 is meant to provide a reusable optimal collaboration model for open source so
- Forking a project for stabilization MAY be done unilaterally and without agreement of project maintainers.
- A patch to a stabilization project declared "stable" SHALL be accompanied by a reproducible test case.
### Evolution of Public Contracts
### Evolution of public contracts
- All Public Contracts (APIs or protocols) SHALL be documented.
- All Public Contracts SHOULD have space for extensibility and experimentation.
@ -162,7 +162,7 @@ C4 is meant to provide a reusable optimal collaboration model for open source so
- Old names SHALL NOT be reused by new features.
- When old names are removed, their implementations MUST provoke an exception (assertion) if used by applications.
### Project Administration
### Project administration
- The project founders SHALL act as Administrators to manage the set of project Maintainers.
- The Administrators SHALL ensure their own succession over time by promoting the most effective Maintainers.
- We are also available via [HackerOne](https://hackerone.com/monero)
@ -50,7 +50,7 @@ Monero is a private, secure, untraceable, decentralised digital currency. You ar
**Untraceability:** By taking advantage of ring signatures, a special property of a certain type of cryptography, Monero is able to ensure that transactions are not only untraceable, but have an optional measure of ambiguity that ensures that transactions cannot easily be tied back to an individual user or computer.
## About this Project
## About this project
This is the core implementation of Monero. It is open source and completely free to use without restrictions, except for those specified in the license agreement below. There are no restrictions on anyone creating an alternative implementation of Monero that uses the protocol and network in a compatible manner.
@ -58,7 +58,7 @@ As with many development projects, the repository on Github is considered to be
**Anyone is welcome to contribute to Monero's codebase!** If you have a fix or code change, feel free to submit it as a pull request directly to the "master" branch. In cases where the change is relatively small or does not affect other parts of the codebase it may be merged in immediately by any one of the collaborators. On the other hand, if the change is particularly large or complex, it is expected that it will be discussed at length either well in advance of the pull request being submitted, or even directly on the pull request.
## Supporting the Project
## Supporting the project
Monero development can be supported directly through donations.
@ -86,21 +86,17 @@ There are also several mining pools that kindly donate a portion of their fees,
See [LICENSE](LICENSE).
# Contributing
## Contributing
If you want to help out, see [CONTRIBUTING](CONTRIBUTING.md) for a set of guidelines.
## Vulnerability Response Process
## Scheduled mandatory software upgrades
See [Vulnerability Response Process](VULNERABILITY_RESPONSE_PROCESS.md).
Monero uses a fixed-schedule network consensus protocol upgrade (hard fork) mechanism to implement new features. This means that users of Monero (end users and service providers) need to run current versions and upgrade their software on a regular schedule. Network consensus protocol upgrades occur during the months of March and September. Required software for these consensus protocol upgrades is available prior to the date of the consensus protocol upgrade. Please check the git repository prior to this date for the proper Monero software version. Below is the historical schedule and the projected schedule for the next upgrade.
Monero uses a fixed-schedule mandatory software upgrade (hard fork) mechanism to implement new features. This means that users of Monero (end users and service providers) need to run current versions and upgrade their software on a regular schedule. Mandatory software upgrades occur during the months of March and September. The required software for these upgrades will be available prior to the scheduled date. Please check the repository prior to this date for the proper Monero software version. Below is the historical schedule and the projected schedule for the next upgrade.
Dates are provided in the format YYYY-MM-DD.
| Consensus Upgrade Block Height | Date | Consensus version | Minimum Monero Version | Recommended Monero Version | Details |
| Software upgrade block height | Date | Fork version | Minimum Monero version | Recommended Monero version | Details |
@ -111,11 +107,11 @@ Dates are provided in the format YYYY-MM-DD.
X's indicate that these details have not been determined as of commit date, 2017-09-20.
## Monero release staging schedule and protocol
## Release staging schedule and protocol
Approximately 3 months prior to a Network Consensus Protocol Upgrade, a branch from Master will be created with the new release version tag. Pull requests that address bugs should then be made to both Master and the new release branch. Pull requests that require extensive review and testing (generally, optmizations and new features) should *not* be made to the release branch.
Approximately three months prior to a scheduled mandatory software upgrade, a branch from Master will be created with the new release version tag. Pull requests that address bugs should then be made to both Master and the new release branch. Pull requests that require extensive review and testing (generally, optimizations and new features) should *not* be made to the release branch.
## Installing Monero from a Package
## Installing Monero from a package
Packages are available for
@ -150,11 +146,11 @@ Installing a snap is very quick. Snaps are secure. They are isolated with all of
Packaging for your favorite distribution would be a welcome contribution!
## Compiling Monero from Source
## Compiling Monero from source
### Dependencies
The following table summarizes the tools and libraries required to build. A
The following table summarizes the tools and libraries required to build. A
few of the libraries are also included in this repository (marked as
"Vendored"). By default, the build uses the library installed on the system,
and ignores the vendored sources. However, if no library is found installed on
@ -163,7 +159,7 @@ sources are also used for statically-linked builds because distribution
packages often include only shared library binaries (`.so`) but not static
library archives (`.a`).
| Dep | Min. Version | Vendored | Debian/Ubuntu Pkg | Arch Pkg | Optional | Purpose |
| Dep | Min. version | Vendored | Debian/Ubuntu pkg | Arch pkg | Optional | Purpose |
| GCC | 4.7.3 | NO | `build-essential` | `base-devel` | NO | |
| CMake | 3.0.0 | NO | `cmake` | `cmake` | NO | |
@ -265,7 +261,7 @@ Tested on a Raspberry Pi Zero with a clean install of minimal Raspbian Stretch (
* You may wish to reduce the size of the swap file after the build has finished, and delete the boost directory from your home directory
#### *Note for Raspbian Jessie Users:*
#### *Note for Raspbian Jessie users:*
If you are using the older Raspbian Jessie image, compiling Monero is a bit more complicated. The version of Boost available in the Debian Jessie repositories is too old to use with Monero, and thus you must compile a newer version yourself. The following explains the extra steps, and has been tested on a Raspberry Pi 2 with a clean install of minimal Raspbian Jessie.
@ -305,7 +301,7 @@ POSIX system. The toolchain runs within the environment and *cross-compiles*
binaries that can run outside of the environment as a regular Windows
application.
**Preparing the Build Environment**
**Preparing the build environment**
* Download and install the [MSYS2 installer](http://msys2.github.io), either the 64-bit or the 32-bit package, depending on your system.
* Open the MSYS shell via the `MSYS2 Shell` shortcut
@ -457,7 +453,7 @@ Then you can run make as usual.
By default, in either dynamically or statically linked builds, binaries target the specific host processor on which the build happens and are not portable to other processors. Portable binaries can be built using the following targets:
@ -519,11 +515,11 @@ TAILS ships with a very restrictive set of firewall rules. Therefore, you need t
`./monero-wallet-cli`
# Debugging
## Debugging
This section contains general instructions for debugging failed installs or problems encountered with Monero. First ensure you are running the latest version built from the github repo.
This section contains general instructions for debugging failed installs or problems encountered with Monero. First ensure you are running the latest version built from the Github repo.
## Obtaining Stack Traces and Core Dumps on Unix Systems
### Obtaining stack traces and core dumps on Unix systems
We generally use the tool `gdb` (GNU debugger) to provide stack trace functionality, and `ulimit` to provide core dumps in builds which crash or segfault.
@ -563,13 +559,13 @@ Pass command-line options with `--args` followed by the relevant arguments
Type `run` to run monerod
## Analysing Memory Corruption
### Analysing memory corruption
We use the tool `valgrind` for this.
Run with `valgrind /path/to/monerod`. It will be slow.
## LMDB
### LMDB
Instructions for debugging suspected blockchain corruption as per @HYC
Riccardo Spagni
6 years ago