cerc-io/solidity
10
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #10955 from ethereum/docsupdate

Browse Source 
[DOCS] Updating contributing section and fixing capitalisation
This commit is contained in:
Franziska Heintel 2021-02-15 17:11:48 +01:00 committed by GitHub
commit d081b49af9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 45 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/contributing.rst
View File

@ -9,14 +9,14 @@ In particular, we appreciate support in the following areas:
* Reporting issues. * Reporting issues.
* Fixing and responding to `Solidity's GitHub issues * Fixing and responding to `Solidity's GitHub issues
<https://github.com/ethereum/solidity/issues>`_, especially those tagged as <https://github.com/ethereum/solidity/issues>`_, especially those tagged as
`good first issue <https://github.com/ethereum/solidity/labels/good%20first%20issue>`_ which are `"good first issue" <https://github.com/ethereum/solidity/labels/good%20first%20issue>`_ which are
meant as introductory issues for external contributors. meant as introductory issues for external contributors.
* Improving the documentation. * Improving the documentation.
* Translating the documentation into more languages. * Translating the documentation into more languages.
* Responding to questions from other users on `StackExchange * Responding to questions from other users on `StackExchange
<https://ethereum.stackexchange.com>`_ and the `Solidity Gitter Chat <https://ethereum.stackexchange.com>`_ and the `Solidity Gitter Chat
<https://gitter.im/ethereum/solidity>`_. <https://gitter.im/ethereum/solidity>`_.
* Getting involved in the language design process by joining language design calls, proposing language changes or new features and providing feedback. * Getting involved in the language design process by proposing language changes or new features in the `Solidity forum <https://forum.soliditylang.org/>`_ and providing feedback.
To get started, you can try :ref:`building-from-source` in order to familiarize To get started, you can try :ref:`building-from-source` in order to familiarize
yourself with the components of Solidity and the build process. Also, it may be yourself with the components of Solidity and the build process. Also, it may be
@ -42,12 +42,11 @@ To report an issue, please use the
`GitHub issues tracker <https://github.com/ethereum/solidity/issues>`_. When `GitHub issues tracker <https://github.com/ethereum/solidity/issues>`_. When
reporting issues, please mention the following details: reporting issues, please mention the following details:
* Which version of Solidity you are using. * Solidity version.
* What was the source code (if applicable). * Source code (if applicable).
* Which platform are you running on. * Operating system.
* How to reproduce the issue. * Steps to reproduce the issue.
* What was the result of the issue. * Actual vs. expected behaviour.
* What the expected behaviour is.
Reducing the source code that caused the issue to a bare minimum is always Reducing the source code that caused the issue to a bare minimum is always
very helpful and sometimes even clarifies a misunderstanding. very helpful and sometimes even clarifies a misunderstanding.
@ -460,17 +459,26 @@ needed for documentation and checks for any problems such as broken links or syn
Solidity Language Design Solidity Language Design
======================== ========================
If you want to get involved in the language design process and share your ideas, please join the `solidity-users forum <https://groups.google.com/g/solidity-users>`_, To actively get involved in the language design process and share your ideas concerning the future of Solidity,
where existing properties of the language and proposals for new features can be discussed. please join the `Solidity forum <https://forum.soliditylang.org/>`_.
We regularly host language design discussion calls, in which selected topics, issues or feature implementations are debated in detail. The invitation The Solidity forum serves as the place to propose and discuss new language features and their implementation in
to those calls is shared via the aforementioned forum. We are also sharing feedback surveys and other language design relevant content in this forum. the early stages of ideation or modifications of existing features.
As soon as proposals get more tangible, their
implementation will also be discussed in the `Solidity GitHub repository <https://github.com/ethereum/solidity>`_
in the form of issues.
In addition to the forum and issue discussions, we regularly host language design discussion calls in which selected
topics, issues or feature implementations are debated in detail. The invitation to those calls is shared via the forum.
We are also sharing feedback surveys and other content that is relevant to language design in the forum.
If you want to know where the team is standing in terms or implementing new features, you can follow the implementation status in the `Solidity Github project <https://github.com/ethereum/solidity/projects/43>`_.
Issues in the design backlog need further specification and will either be discussed in a language design call or in a regular team call. You can
see the upcoming changes for the next breaking release by changing from the default branch (`develop`) to the `breaking branch <https://github.com/ethereum/solidity/tree/breaking>`_.
For ad-hoc cases and questions you can reach out to us via the `Solidity-dev Gitter channel <https://gitter.im/ethereum/solidity-dev>`_, a For ad-hoc cases and questions you can reach out to us via the `Solidity-dev Gitter channel <https://gitter.im/ethereum/solidity-dev>`_, a
dedicated chatroom for conversations around the Solidity compiler and language development. dedicated chatroom for conversations around the Solidity compiler and language development.
You can follow the implementation status of new features in the `Solidity Github project <https://github.com/ethereum/solidity/projects/43>`_.
Issues in the design backlog need further specification and will either be discussed in a language design call or in a regular team call. You can
see the upcoming changes for the next breaking release by changing from the default branch (`develop`) to the `breaking branch <https://github.com/ethereum/solidity/tree/breaking>`_.
We are happy to hear your thoughts on how we can improve the language design process to be even more collaborative and transparent. We are happy to hear your thoughts on how we can improve the language design process to be even more collaborative and transparent.

12
docs/installing-solidity.rst
View File

@ -330,7 +330,7 @@ The following are dependencies for all builds of Solidity:
Starting from 0.5.10 linking against Boost 1.70+ should work without manual intervention. Starting from 0.5.10 linking against Boost 1.70+ should work without manual intervention.
Minimum compiler versions Minimum Compiler Versions
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
The following C++ compilers and their minimum versions can build the Solidity codebase: The following C++ compilers and their minimum versions can build the Solidity codebase:
@ -547,10 +547,10 @@ of the current nightly build, but without the ``prerelease`` specifier.
Example: Example:
0. the 0.4.0 release is made 0. The 0.4.0 release is made.
1. nightly build has a version of 0.4.1 from now on 1. The nightly build has a version of 0.4.1 from now on.
2. non-breaking changes are introduced - no change in version 2. Non-breaking changes are introduced --> no change in version.
3. a breaking change is introduced - version is bumped to 0.5.0 3. A breaking change is introduced --> version is bumped to 0.5.0.
4. the 0.5.0 release is made 4. The 0.5.0 release is made.
This behaviour works well with the :ref:`version pragma <version_pragma>`. This behaviour works well with the :ref:`version pragma <version_pragma>`.

28
docs/using-the-compiler.rst
View File

@ -1,5 +1,5 @@
****************** ******************
Using the compiler Using the Compiler
****************** ******************
.. index:: ! commandline compiler, compiler;commandline, ! solc, ! linker .. index:: ! commandline compiler, compiler;commandline, ! solc, ! linker
@ -12,14 +12,14 @@ Using the Commandline Compiler
.. note:: .. note::
This section does not apply to :ref:`solcjs <solcjs>`, not even if it is used in commandline mode. This section does not apply to :ref:`solcjs <solcjs>`, not even if it is used in commandline mode.
Basic usage Basic Usage
----------- -----------
One of the build targets of the Solidity repository is ``solc``, the solidity commandline compiler. One of the build targets of the Solidity repository is ``solc``, the solidity commandline compiler.
Using ``solc --help`` provides you with an explanation of all options. The compiler can produce various outputs, ranging from simple binaries and assembly over an abstract syntax tree (parse tree) to estimations of gas usage. Using ``solc --help`` provides you with an explanation of all options. The compiler can produce various outputs, ranging from simple binaries and assembly over an abstract syntax tree (parse tree) to estimations of gas usage.
If you only want to compile a single file, you run it as ``solc --bin sourceFile.sol`` and it will print the binary. If you want to get some of the more advanced output variants of ``solc``, it is probably better to tell it to output everything to separate files using ``solc -o outputDirectory --bin --ast-json --asm sourceFile.sol``. If you only want to compile a single file, you run it as ``solc --bin sourceFile.sol`` and it will print the binary. If you want to get some of the more advanced output variants of ``solc``, it is probably better to tell it to output everything to separate files using ``solc -o outputDirectory --bin --ast-json --asm sourceFile.sol``.
Optimizer options Optimizer Options
----------------- -----------------
Before you deploy your contract, activate the optimizer when compiling using ``solc --optimize --bin sourceFile.sol``. Before you deploy your contract, activate the optimizer when compiling using ``solc --optimize --bin sourceFile.sol``.
@ -33,7 +33,7 @@ This parameter has effects on the following (this might change in the future):
- the size of the binary search in the function dispatch routine - the size of the binary search in the function dispatch routine
- the way constants like large numbers or strings are stored - the way constants like large numbers or strings are stored
Path remapping Path Remapping
-------------- --------------
The commandline compiler will automatically read imported files from the filesystem, but The commandline compiler will automatically read imported files from the filesystem, but
@ -64,7 +64,7 @@ Everything inside the path specified via ``--base-path`` is always allowed.
.. _library-linking: .. _library-linking:
Library linking Library Linking
--------------- ---------------
If your contracts use :ref:`libraries <libraries>`, you will notice that the bytecode contains substrings of the form ``__$53aea86b7d70b31448b230b20ae141a537$__``. These are placeholders for the actual library addresses. If your contracts use :ref:`libraries <libraries>`, you will notice that the bytecode contains substrings of the form ``__$53aea86b7d70b31448b230b20ae141a537$__``. These are placeholders for the actual library addresses.
@ -104,7 +104,7 @@ If ``solc`` is called with the option ``--link``, all input files are interprete
.. _evm-version: .. _evm-version:
.. index:: ! EVM version, compile target .. index:: ! EVM version, compile target
Setting the EVM version to target Setting the EVM Version to Target
********************************* *********************************
When you compile your contract code you can specify the Ethereum virtual machine When you compile your contract code you can specify the Ethereum virtual machine
@ -135,7 +135,7 @@ key in the ``"settings"`` field:
} }
} }
Target options Target Options
-------------- --------------
Below is a list of target EVM versions and the compiler-relevant changes introduced Below is a list of target EVM versions and the compiler-relevant changes introduced
@ -540,7 +540,7 @@ Output Description
} }
Error types Error Types
~~~~~~~~~~~ ~~~~~~~~~~~
1. ``JSONError``: JSON input doesn't conform to the required format, e.g. input is not a JSON object, the language is not supported, etc. 1. ``JSONError``: JSON input doesn't conform to the required format, e.g. input is not a JSON object, the language is not supported, etc.
@ -560,7 +560,7 @@ Error types
.. _compiler-tools: .. _compiler-tools:
Compiler tools Compiler Tools
************** **************
solidity-upgrade solidity-upgrade
@ -583,7 +583,7 @@ would need plenty of repetitive manual adjustments otherwise.
``solidity-upgrade`` is not considered to be complete or free from bugs, so ``solidity-upgrade`` is not considered to be complete or free from bugs, so
please use with care. please use with care.
How it works How it Works
~~~~~~~~~~~~ ~~~~~~~~~~~~
You can pass (a) Solidity source file(s) to ``solidity-upgrade [files]``. If You can pass (a) Solidity source file(s) to ``solidity-upgrade [files]``. If
@ -624,7 +624,7 @@ the latest version of the compiler.
.. _upgrade-modules: .. _upgrade-modules:
Available upgrade modules Available Upgrade Modules
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------+---------+--------------------------------------------------+ +----------------------------+---------+--------------------------------------------------+
@ -686,7 +686,7 @@ Synopsis
Bug Reports / Feature requests Bug Reports / Feature Requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you found a bug or if you have a feature request, please If you found a bug or if you have a feature request, please
@ -731,7 +731,7 @@ Assume that you have the following contract in ``Source.sol``:
Required changes Required Changes
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
The above contract will not compile starting from 0.7.0. To bring the contract up to date with the The above contract will not compile starting from 0.7.0. To bring the contract up to date with the
@ -740,7 +740,7 @@ current Solidity version, the following upgrade modules have to be executed:
:ref:`available modules <upgrade-modules>` for further details. :ref:`available modules <upgrade-modules>` for further details.
Running the upgrade Running the Upgrade
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
It is recommended to explicitly specify the upgrade modules by using ``--modules`` argument. It is recommended to explicitly specify the upgrade modules by using ``--modules`` argument.