diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 17d894dddb..f9a34c49dd 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -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 `_. 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 `_ +* Browse issues labelled as ``good first issue`` in the + `Corda GitHub Issues `_ - * 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 `_ - - * 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 `_ +* Ask in the ``#design`` channel of the `Corda Slack `_ 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 ` +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 `. +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 `. +You can test your changes against CorDapps defined in other repos by following the instructions +:doc:`here `. + +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 `. + + +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) `_ +3. Include the change in the :doc:`changelog ` if the change is external and therefore visible to CorDapp + developers and/or node operators +4. :doc:`Build the docs locally ` +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 ` and - :doc:`release notes ` where applicable - * State that you are in agreement with the terms of - `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 `_ -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 \ No newline at end of file + * 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 `_ + +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 \ No newline at end of file diff --git a/docs/source/getting-set-up.rst b/docs/source/getting-set-up.rst index aef199da90..ab5f604ca2 100644 --- a/docs/source/getting-set-up.rst +++ b/docs/source/getting-set-up.rst @@ -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 `_) +* :ref:`windows-label` (or `in video form `__) -* :ref:`mac-label` (or `in video form `_) +* :ref:`mac-label` (or `in video form `__) .. _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 ` 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 `. You may want to refer to the :doc:`API docs `, the +:doc:`Hello, World tutorial `. You may want to refer to the API documentation, the :doc:`flow cookbook ` and the `samples `_ along the way. -If you encounter any issues, please see the :doc:`troubleshooting` page, or get in touch with us on the -`forums `_ or via `slack `_. \ No newline at end of file +If you encounter any issues, please see the :doc:`troubleshooting` page, or ask on +`Stack Overflow `_ or via `our Slack channels `_. \ No newline at end of file