ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-02-04 02:01:13 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Reflects master changes to set up and contrib instructions. (#3264)

Browse Source
This commit is contained in:
Joel Dudley 2018-05-30 13:45:58 +01:00 committed by GitHub
parent 5ee91e6425
commit 593708e885
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 164 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
docs/source/contributing.rst
View File

@ -1,7 +1,9 @@
Contributing
============
Corda is an open-source project and we welcome contributions. This guide explains how to contribute back to Corda.
Corda is an open-source project and contributions are welcome. Our contributing philosophy is described in
`CONTRIBUTING.md <https://github.com/corda/corda/blob/master/CONTRIBUTING.md>`_. This guide explains the mechanics
of contributing to Corda.
.. contents::
@ -9,19 +11,15 @@ Identifying an area to contribute
---------------------------------
There are several ways to identify an area where you can contribute to Corda:
* Browse issues labelled as ``HelpWanted`` on the
`Corda JIRA board <https://r3-cev.atlassian.net/issues/?jql=labels%20%3D%20HelpWanted>`_
* Browse issues labelled as ``good first issue`` in the
`Corda GitHub Issues <https://github.com/corda/corda/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_
* Any issue with a ``HelpWanted`` label is considered ideal for open-source contributions
* If there is a feature you would like to add and there isn't a corresponding issue labelled as ``HelpWanted``, that
doesn't mean your contribution isn't welcome. Please reach out on the Corda Slack channel (see below) to clarify
* Any issue with a ``good first issue`` label is considered ideal for open-source contributions
* If there is a feature you would like to add and there isn't a corresponding issue labelled as ``good first issue``,
that doesn't mean your contribution isn't welcome. Please reach out on the ``#design`` channel to clarify (see
below)
* Check the `Corda GitHub issues <https://github.com/corda/corda/issues>`_
* It's always worth checking in the Corda Slack channel (see below) whether a given issue is a good target for your
contribution. Someone else may already be working on it, or it may be blocked by an on-going piece of work
* Ask in the `Corda Slack channel <http://slack.corda.net/>`_
* Ask in the ``#design`` channel of the `Corda Slack <http://slack.corda.net/>`_
Making the required changes
---------------------------
@ -30,35 +28,127 @@ Making the required changes
2. Clone the fork to your local machine
3. Make the changes, in accordance with the :doc:`code style guide </codestyle>`
Things to check
^^^^^^^^^^^^^^^
Is your error handling up to scratch?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Errors should not leak to the UI. When writing tools intended for end users, like the node or command line tools,
remember to add ``try``/``catch`` blocks. Throw meaningful errors. For example, instead of throwing an
``OutOfMemoryError``, use the error message to indicate that a file is missing, a network socket was unreachable, etc.
Tools should not dump stack traces to the end user.
Look for API breaks
~~~~~~~~~~~~~~~~~~~
We have an automated checker tool that runs as part of our continuous integration pipeline and helps a lot, but it
can't catch semantic changes where the behavior of an API changes in ways that might violate app developer expectations.
Suppress inevitable compiler warnings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Compiler warnings should have a ``@Suppress`` annotation on them if they're expected and can't be avoided.
Remove deprecated functionality
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When deprecating functionality, make sure you remove the deprecated uses in the codebase.
Avoid making formatting changes as you work
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In Kotlin 1.2.20, new style guide rules were implemented. The new Kotlin style guide is significantly more detailed
than before and IntelliJ knows how to implement those rules. Re-formatting the codebase creates a lot of diffs that
make merging more complicated.
Things to consider when writing CLI apps
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Set exit codes using ``exitProcess``. Zero means success. Other numbers mean errors. Setting a unique error code
(starting from 1) for each thing that can conceivably break makes your tool shell-scripting friendly
* Do a bit of work to figure out reasonable defaults. Nobody likes having to set a dozen flags before the tool will
cooperate
* Your ``--help`` text or other docs should ideally include examples. Writing examples is also a good way to find out
that your program requires a dozen flags to do anything
* Flags should have sensible defaults
* Don’t print logging output to the console unless the user requested it via a ``–verbose`` flag (conventionally
shortened to ``-v``) or a ``–log-to-console`` flag. Logs should be either suppressed or saved to a text file during
normal usage, except for errors, which are always OK to print
Testing the changes
-------------------
Adding tests
^^^^^^^^^^^^
Unit tests and integration tests for external API changes must cover Java and Kotlin. For internal API changes these
tests can be scaled back to kotlin only.
Running the tests
^^^^^^^^^^^^^^^^^
Your changes must pass the tests described :doc:`here </testing>`.
Manual testing
^^^^^^^^^^^^^^
Before sending that code for review, spend time poking and prodding the tool and thinking, “Would the experience of
using this feature make my mum proud of me?”. Automated tests are not a substitute for dogfooding.
Building against the master branch
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You may also want to test your changes against a CorDapp defined outside of the Corda repo. To do so, please follow the
instructions :doc:`here </building-against-master>`.
You can test your changes against CorDapps defined in other repos by following the instructions
:doc:`here </building-against-master>`.
Running the API scanner
^^^^^^^^^^^^^^^^^^^^^^^
Your changes must also not break compatibility with existing public API. We have an API scanning tool which runs as part of the build
process which can be used to flag up any accidental changes, which is detailed :doc:`here </api-scanner>`.
Updating the docs
-----------------
Any changes to Corda's public API must be documented as follows:
1. Add comments and javadocs/kdocs. API functions must have javadoc/kdoc comments and sentences must be terminated
with a full stop. We also start comments with capital letters, even for inline comments. Where Java APIs have
synonyms (e.g. ``%d`` and ``%date``), we prefer the longer form for legibility reasons. You can configure your IDE
to highlight these in bright yellow
2. Update the relevant `.rst file(s) <https://github.com/corda/corda/tree/master/docs/source>`_
3. Include the change in the :doc:`changelog </changelog>` if the change is external and therefore visible to CorDapp
developers and/or node operators
4. :doc:`Build the docs locally </building-the-docs>`
5. Check the built .html files (under ``docs/build/html``) for the modified pages to ensure they render correctly
6. If relevant, add a sample. Samples are one of the key ways in which users learn about what the platform can do.
If you add a new API or feature and don't update the samples, your work will be much less impactful
Merging the changes back into Corda
-----------------------------------
1. Create a pull request from your fork to the master branch of the Corda repo
2. Complete the pull-request checklist in the comments box:
1. Create a pull request from your fork to the ``master`` branch of the Corda repo
* State that you have run the tests
* State that you have included JavaDocs for any new public APIs
* State that you have included the change in the :doc:`changelog </changelog>` and
:doc:`release notes </release-notes>` where applicable
* State that you are in agreement with the terms of
`CONTRIBUTING.md <https://github.com/corda/corda/blob/master/CONTRIBUTING.md>`_
2. In the PR comments box:
3. Request a review from a member of the Corda platform team via the `Corda Slack channel <http://slack.corda.net/>`_
4. Wait for your PR to pass all four types of continuous integration tests (integration, API stability, build and unit)
* Complete the pull-request checklist:
* Currently, external contributors cannot see the output of these tests. If your PR fails a test that passed
locally, ask the reviewer for further details
* [ ] Have you run the unit, integration and smoke tests as described here? https://docs.corda.net/head/testing.html
* [ ] If you added/changed public APIs, did you write/update the JavaDocs?
* [ ] If the changes are of interest to application developers, have you added them to the changelog, and potentially
release notes?
* [ ] If you are contributing for the first time, please read the agreement in CONTRIBUTING.md now and add to this
Pull Request that you agree to it.
5. Once a reviewer has approved the PR and the tests have passed, squash-and-merge the PR as a single commit
* Add a clear description of the purpose of the PR
* Add the following statement to confirm that your contribution is your own original work: "I hereby certify that my contribution is in accordance with the Developer Certificate of Origin (https://github.com/corda/corda/blob/master/CONTRIBUTING.md#developer-certificate-of-origin)."
4. Request a review from a member of the Corda platform team via the `#design channel <http://slack.corda.net/>`_
5. The reviewer will either:
* Accept and merge your PR
* Request that you make further changes. Do this by committing and pushing the changes onto the branch you are PRing
into Corda. The PR will be updated automatically

77
docs/source/getting-set-up.rst
View File

@ -6,10 +6,10 @@ Software requirements
Corda uses industry-standard tools:
* **Oracle JDK 8 JVM** - minimum supported version **8u131**
* **IntelliJ IDEA** - supported versions **2017.1**, **2017.2** and **2017.3**
* **IntelliJ IDEA** - supported versions **2017.x** and **2018.x**
* **Git**
We also use Gradle and Kotlin, but you do not need to install them. A standalone Gradle wrapper is provided, and it
We also use Gradle and Kotlin, but you do not need to install them. A standalone Gradle wrapper is provided, and it
will download the correct version of Kotlin.
Please note:
@ -39,9 +39,9 @@ any issues, please consult the :doc:`troubleshooting` page, or reach out on `Sla
The set-up instructions are available for the following platforms:
* :ref:`windows-label` (or `in video form <https://vimeo.com/217462250>`_)
* :ref:`windows-label` (or `in video form <https://vimeo.com/217462250>`__)
* :ref:`mac-label` (or `in video form <https://vimeo.com/217462230>`_)
* :ref:`mac-label` (or `in video form <https://vimeo.com/217462230>`__)
.. _windows-label:
@ -57,7 +57,8 @@ Java
3. Toggle "Accept License Agreement"
4. Click the download link for jdk-8uXXX-windows-x64.exe (where "XXX" is the latest minor version number)
5. Download and run the executable to install Java (use the default settings)
6. Open a new command prompt and run ``java -version`` to test that Java is installed correctly
6. Add Java to the PATH environment variable by following the instructions at https://docs.oracle.com/javase/7/docs/webnotes/install/windows/jdk-installation-windows.html#path
7. Open a new command prompt and run ``java -version`` to test that Java is installed correctly
Git
^^^
@ -75,7 +76,7 @@ Download a sample project
^^^^^^^^^^^^^^^^^^^^^^^^^
1. Open a command prompt
2. Clone the CorDapp example repo by running ``git clone https://github.com/corda/cordapp-example``
3. Move into the cordapp-example folder by running ``cd cordapp-example``
3. Move into the ``cordapp-example`` folder by running ``cd cordapp-example``
Run from the command prompt
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -87,16 +88,22 @@ Run from the command prompt
Run from IntelliJ
^^^^^^^^^^^^^^^^^
1. Open IntelliJ Community Edition
2. On the splash screen, click "Open" (do NOT click "Import Project") and select the cordapp-example folder
2. On the splash screen, click ``Open`` (do **not** click ``Import Project``) and select the ``cordapp-example`` folder
.. warning:: If you click "Import Project" instead of "Open", the project's run configurations will be erased!
.. warning:: If you click ``Import Project`` instead of ``Open``, the project's run configurations will be erased!
3. Once the project is open, click "File > Project Structure". Under "Project SDK:", set the project SDK by clicking "New...", clicking "JDK", and navigating to C:\\Program Files\\Java\\jdk1.8.0_XXX (where "XXX" is the latest minor version number). Click "OK".
4. Click "View > Tool Windows > Event Log", and click "Import Gradle project", then "OK". Wait, and click "OK" again when the "Gradle Project Data To Import" window appears
5. Wait for indexing to finish (a progress bar will display at the bottom-right of the IntelliJ window until indexing is complete)
6. At the top-right of the screen, to the left of the green "play" arrow, you should see a dropdown. In that dropdown, select "Run Example Cordapp - Kotlin" and click the green "play" arrow.
7. Wait until the run windows displays the message "Webserver started up in XX.X sec"
8. Test the CorDapp is running correctly by visiting the front end at http://localhost:10007/web/example/
3. Once the project is open, click ``File``, then ``Project Structure``. Under ``Project SDK:``, set the project SDK by
clicking ``New...``, clicking ``JDK``, and navigating to ``C:\\Program Files\\Java\\jdk1.8.0_XXX`` (where ``XXX`` is
the latest minor version number). Click "OK"
4. Again under ``File`` then ``Project Structure``, select ``Modules``. Click ``+``, then ``Import Module``, then select
the ``cordapp-example`` folder and click ``Open``. Choose to ``Import module from external model``, select
``Gradle``, click ``Next`` then ``Finish`` (leaving the defaults) and ``OK``
5. Wait for the indexing to finish (a progress bar will display at the bottom-right of the IntelliJ window until indexing
is complete)
6. At the top-right of the screen, to the left of the green ``play`` arrow, you should see a dropdown. In that
dropdown, select ``Run Example Cordapp - Kotlin`` and click the green ``play`` arrow.
7. Wait until the run windows displays the message ``Webserver started up in XX.X sec``
8. Test the CorDapp is running correctly by visiting the front end at `http://localhost:10007/web/example/
.. _mac-label:
@ -107,11 +114,12 @@ Mac
Java
^^^^
1. Open "System Preferences > Java"
2. In the Java Control Panel, if an update is available, click "Update Now"
3. In the "Software Update" window, click "Install Update". If required, enter your password and click "Install Helper" when prompted
4. Wait for a pop-up window indicating that you have successfully installed the update, and click "Close"
5. Open a new terminal and type ``java -version`` to test that Java is installed correctly
1. Visit http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
2. Scroll down to "Java SE Development Kit 8uXXX" (where "XXX" is the latest minor version number)
3. Toggle "Accept License Agreement"
4. Click the download link for jdk-8uXXX-macosx-x64.dmg (where "XXX" is the latest minor version number)
5. Download and run the executable to install Java (use the default settings)
6. Open a new terminal window and run ``java -version`` to test that Java is installed correctly
IntelliJ
^^^^^^^^
@ -122,7 +130,7 @@ Download a sample project
^^^^^^^^^^^^^^^^^^^^^^^^^
1. Open a terminal
2. Clone the CorDapp example repo by running ``git clone https://github.com/corda/cordapp-example``
3. Move into the cordapp-example folder by running ``cd cordapp-example``
3. Move into the ``cordapp-example`` folder by running ``cd cordapp-example``
Run from the terminal
^^^^^^^^^^^^^^^^^^^^^
@ -134,13 +142,22 @@ Run from the terminal
Run from IntelliJ
^^^^^^^^^^^^^^^^^
1. Open IntelliJ Community Edition
2. On the splash screen, click "Open" (do NOT click "Import Project") and select the cordapp-example folder
3. Once the project is open, click "File > Project Structure". Under "Project SDK:", set the project SDK by clicking "New...", clicking "JDK", and navigating to /Library/Java/JavaVirtualMachines/jdk1.8.0_XXX (where "XXX" is the latest minor version number). Click "OK".
4. Click "View > Tool Windows > Event Log", and click "Import Gradle project", then "OK". Wait, and click "OK" again when the "Gradle Project Data To Import" window appears
5. Wait for indexing to finish (a progress bar will display at the bottom-right of the IntelliJ window until indexing is complete)
6. At the top-right of the screen, to the left of the green "play" arrow, you should see a dropdown. In that dropdown, select "Run Example Cordapp - Kotlin" and click the green "play" arrow.
7. Wait until the run windows displays the message "Webserver started up in XX.X sec"
8. Test the CorDapp is running correctly by visiting the front end at http://localhost:10007/web/example/
2. On the splash screen, click ``Open`` (do **not** click ``Import Project``) and select the ``cordapp-example`` folder
.. warning:: If you click ``Import Project`` instead of ``Open``, the project's run configurations will be erased!
3. Once the project is open, click ``File``, then ``Project Structure``. Under ``Project SDK:``, set the project SDK by
clicking ``New...``, clicking ``JDK``, and navigating to ``C:\\Program Files\\Java\\jdk1.8.0_XXX`` (where ``XXX`` is
the latest minor version number). Click "OK"
4. Again under ``File`` then ``Project Structure``, select ``Modules``. Click ``+``, then ``Import Module``, then select
the ``cordapp-example`` folder and click ``Open``. Choose to ``Import module from external model``, select
``Gradle``, click ``Next`` then ``Finish`` (leaving the defaults) and ``OK``
5. Wait for the indexing to finish (a progress bar will display at the bottom-right of the IntelliJ window until indexing
is complete)
6. At the top-right of the screen, to the left of the green ``play`` arrow, you should see a dropdown. In that
dropdown, select ``Run Example Cordapp - Kotlin`` and click the green ``play`` arrow.
7. Wait until the run windows displays the message ``Webserver started up in XX.X sec``
8. Test the CorDapp is running correctly by visiting the front end at `http://localhost:10007/web/example/
Corda source code
-----------------
@ -169,8 +186,8 @@ The best way to check that everything is working fine is by taking a deeper look
Next, you should read through :doc:`Corda Key Concepts <key-concepts>` to understand how Corda works.
By then, you'll be ready to start writing your own CorDapps. Learn how to do this in the
:doc:`Hello, World tutorial <hello-world-introduction>`. You may want to refer to the :doc:`API docs <api-index>`, the
:doc:`Hello, World tutorial <hello-world-introduction>`. You may want to refer to the API documentation, the
:doc:`flow cookbook <flow-cookbook>` and the `samples <https://www.corda.net/samples/>`_ along the way.
If you encounter any issues, please see the :doc:`troubleshooting` page, or get in touch with us on the
`forums <https://discourse.corda.net/>`_ or via `slack <http://slack.corda.net/>`_.
If you encounter any issues, please see the :doc:`troubleshooting` page, or ask on
`Stack Overflow <https://stackoverflow.com/questions/tagged/corda>`_ or via `our Slack channels <http://slack.corda.net/>`_.