ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-19 21:17:58 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Combines all contributing info in one place. Clean-up. (#4266)

Browse Source
This commit is contained in:
Joel Dudley 2018-11-20 18:17:11 +00:00 committed by GitHub
parent 0fe7f513e2
commit faa9606dea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 228 additions and 174 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
CONTRIBUTING.md
View File

@ -1,67 +1,5 @@
# Contributing to Corda
## Contributions are Welcome
Corda is an open-source project and contributions are welcome!
We welcome contributions to Corda! Here's how to go about it.
## Mission
Corda is an open source project with the aim of developing an enterprise-grade distributed ledger platform for business across a variety of industries. Corda was designed and developed to apply the concepts of blockchain and smart contract technologies to the requirements of modern business transactions. It is unique in its aim to build a platform for businesses to transact freely with any counter-party while retaining strict privacy. Corda provides an implementation of this vision in a code base which others are free to build on, contribute to or innovate around. The mission of Corda is further detailed in the [Corda introductory white paper](https://docs.corda.net/_static/corda-introductory-whitepaper.pdf).
The project is supported and maintained by the [R3 Alliance](https://www.r3.com), or R3 for short, which consists of over two hundred firms working together to build and maintain this open source enterprise-grade blockchain platform.
## Scope
We believe one of the things that makes Corda special is its coherent design and we seek to retain this defining characteristic. One of the ways we do this is by encouraging developers of new features to write a design proposal for review, comment and advice before they start work and you are encouraged to take advantage of this process. Posting to the [design](https://cordaledger.slack.com/messages/C3J04VC3V/) channel on Slack is a good way to kick this process off. When reviewing a proposed feature, we use the [Corda Technical Whitepaper](https://docs.corda.net/_static/corda-technical-whitepaper.pdf) as a guide and you are strongly encouraged to study it. This white paper is a living document that is updated from time to time under the guidance of the project leader (see below).
## How to Contribute
Contributions from the community are welcomed and strongly encouraged. From the outset we defined some guidelines to ensure new contributions only ever enhance the project:
* **Quality**: Code in the Corda project should meet the [Corda coding style guidelines](https://docs.corda.net/codestyle.html), with sufficient test-cases, descriptive commit messages, evidence that the contribution does not break any compatibility commitments or cause adverse feature interactions, and evidence of high-quality peer-review.
* **Size**: The Corda project's culture is one of small pull-requests, regularly submitted. The larger a pull-request, the more likely it is that you will be asked to resubmit as a series of self-contained and individually reviewable smaller PRs.
* **Scope**: We try to ensure the Corda project remains coherent and focused so we ask that the feature's scope is within the definition specified in the Technical White Paper.
* **Maintainability**: If the feature will require ongoing maintenance (eg support for a particular brand of database), we may ask you to accept responsibility for maintaining this feature.
* **Non-duplicative**: If the contribution duplicates features that already exist or are already in progress, you may be asked to work with the project maintainers to reconcile this. As the major contributor to Corda, many employees of [R3](https://r3.com) will be working on features at any given time. To avoid surprises and foster transparency, our work tracking system, [Jira](https://r3-cev.atlassian.net/projects/CORDA/summary), is public. In addition, the maintainers and developers on the project are available on the [design](https://cordaledger.slack.com/messages/C3J04VC3V/) channel of our [Slack](https://slack.corda.net/) and they would be delighted to discuss any work you plan to do.
**Advice to contributors**: You are encouraged to join our [Slack](https://slack.corda.net/), observe the [Pull Request](https://github.com/corda/corda/pulls) process in action, contribute to code reviews and start by submitting small changes. [This page](https://docs.corda.net/head/contributing.html) in our docsite shares tips on how to identify areas in which to contribute, and outlines the mechanics for doing so.
To start contributing you can clone our repo and begin making pull requests. All contributions to this project are subject to the terms of the Developer Certificate of Origin, reproduced at the bottom of this page.
## Project Leadership and Maintainers
The leader of this project is currently [Mike Hearn](https://github.com/mikehearn), who is also the Lead Platform Engineer at R3. The project leader will appoint maintainers of the project, to whom responsibility is delegated for merging community contributions into the code base and acting as points of contact. There is currently one such community maintainer, [Joel Dudley](https://github.com/joeldudleyr3). We anticipate additional maintainers joining the project in the future from across the community.
Transparency: In addition to the project lead and maintainer(s), developers employed by R3 who have passed our technical interview process have commit privileges to the repo. All R3 contributions undergo peer review, which is documented in public in GitHub, before they can be merged; they are held to the same standard as all other contributions. The community is encouraged both to observe and participate in this [review process](https://github.com/corda/corda/pulls).
## Community Locations
The Corda maintainers, developers and extended community make active use of the [Corda Slack](http://slack.corda.net/). We also support a very active community of question askers and answerers on [Stack Overflow](https://stackoverflow.com/questions/tagged/corda).
## Transparency and Conflict Policy
The project is supported and maintained by the [R3 Alliance](https://www.r3.com), which consists of over two hundred firms working together to build and maintain this open source enterprise-grade blockchain platform. We develop in the open and publish our [Jira](https://r3-cev.atlassian.net/projects/CORDA/summary) to give everyone visibility. R3 also maintains and distributes a commercial distribution of Corda. Our vision is that distributions of Corda be compatible and interoperable, and our contribution and code review guidelines are designed in part to enable this.
As the R3 Alliance is maintainer of the project and also develops a commercial distribution of Corda, what happens if a member of the community contributes a feature which the R3 team have implemented only in their commercial product? How is this apparent conflict managed? Our approach is simple: if the contribution meets the standards for the project (see above), then the existence of a competing commercial implementation will not be used as a reason to reject it. In other words, it is our policy that should a community feature be contributed which meets the criteria above, we will accept it or work with the contributor to merge/reconcile it with the commercial feature.
## Developer Certificate of Origin
All contributions to this project are subject to the terms of the Developer Certificate of Origin, below:
Developer Certificate of Origin Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 1 Letterman Drive Suite D4700 San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
To find out how to contribute, please see our [contributing docs](https://docs.corda.net/head/contributing-index.html).

4
docs/source/api-scanner.rst
View File

@ -1,5 +1,5 @@
API stability check
===================
Checking API stability
======================
We have committed not to alter Corda's API so that developers will not have to keep rewriting their CorDapps with each
new Corda release. The stable Corda modules are listed :ref:`here <internal-apis-and-stability-guarantees>`. Our CI process runs an "API Stability"

4
docs/source/building-corda.rst
View File

@ -25,8 +25,8 @@ Git
3. Download and run the executable to install Git (use the default installation values) and make a note of the installation directory.
4. Open a new command prompt and type ``git --version`` to test that Git is installed correctly
Buillding Corda
~~~~~~~~~~~~~~~
Building Corda
~~~~~~~~~~~~~~
1. Open a command prompt
2. Run ``git clone https://github.com/corda/corda.git``

4
docs/source/contributing-flow-state-machines.rst
View File

@ -4,8 +4,8 @@
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
How to extend the state machine
===============================
Extending the state machine
===========================
This article explains how to extend the state machine code that underlies flow execution. It is intended for Corda
contributors.

9
docs/source/contributing-index.rst
View File

@ -1,18 +1,17 @@
Contributing
============
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.
Corda is an open-source project and contributions are welcome!
.. toctree::
:maxdepth: 1
contributing-philosophy
contributing
building-corda
testing
api-scanner
building-the-docs
codestyle
cli-ux-guidelines
building-the-docs
api-scanner
contributing-flow-state-machines

71
docs/source/contributing-philosophy.rst Normal file
View File

@ -0,0 +1,71 @@
Contributing philosophy
=======================
.. contents::
Mission
-------
Corda is an open source project with the aim of developing an enterprise-grade distributed ledger platform for business across a variety of
industries. Corda was designed and developed to apply the concepts of blockchain and smart contract technologies to the requirements of
modern business transactions. It is unique in its aim to build a platform for businesses to transact freely with any counter-party while
retaining strict privacy. Corda provides an implementation of this vision in a code base which others are free to build on, contribute to
or innovate around. The mission of Corda is further detailed in the `Corda introductory white paper`_.
The project is supported and maintained by the `R3 Alliance <https://www.r3.com>`_, or R3 for short, which consists of over two hundred firms
working together to build and maintain this open source enterprise-grade blockchain platform.
Community Locations
-------------------
The Corda maintainers, developers and extended community make active use of the following channels:
* The `Corda Slack team <http://slack.corda.net/>`_ for general community discussion, and in particular:
* The ``#contributing`` channel for discussions around contributing
* The ``#design`` channel for discussions around the platform's design
* The `corda-dev mailing list <https://groups.io/g/corda-dev>`_ for discussion regarding Corda's design and roadmap
* The `GitHub issues board <https://github.com/corda/corda/issues>`_ for reporting platform bugs and potential enhancements
* The `Stack Overflow corda tag <https://stackoverflow.com/questions/tagged/corda>`_ for specific technical questions
Project Leadership and Maintainers
----------------------------------
The leader of this project is currently `Mike Hearn <https://github.com/mikehearn>`_, who is also the Lead Platform Engineer at R3. The
project leader appoints the project's Community Maintainers, who are responsible for merging community contributions into the code base and
acting as points of contact.
In addition to the project leader and community maintainer(s), developers employed by R3 who have passed our technical interview process
have commit privileges to the repo. All R3 contributions undergo peer review, which is documented in public in GitHub, before they can be
merged; they are held to the same standard as all other contributions. The community is encouraged both to observe and participate in this
`review process <https://github.com/corda/corda/pulls>`_.
.. _community-maintainers:
Community maintainers
^^^^^^^^^^^^^^^^^^^^^
Current community maintainers:
* `Joel Dudley <https://github.com/joeldudleyr3>`_ - Contact via the `Corda Slack team <http://slack.corda.net/>`_, either in the
``#community`` channel or via direct message using the handle ``@joel``
We anticipate additional maintainers joining the project in the future from across the community.
Existing Contributors
---------------------
Over two hundred individuals have contributed to the development of Corda. You can find a full list of contributors in the
`CONTRIBUTORS.md list <https://github.com/corda/corda/blob/master/CONTRIBUTORS.md>`_.
Transparency and Conflict Policy
--------------------------------
The project is supported and maintained by the `R3 Alliance <https://www.r3.com>`_, which consists of over two hundred firms working together
to build and maintain this open source enterprise-grade blockchain platform. We develop in the open and publish our
`Jira <https://r3-cev.atlassian.net/projects/CORDA/summary>`_ to give everyone visibility. R3 also maintains and distributes a commercial
distribution of Corda. Our vision is that distributions of Corda be compatible and interoperable, and our contribution and code review
guidelines are designed in part to enable this.
As the R3 Alliance is maintainer of the project and also develops a commercial distribution of Corda, what happens if a member of the
community contributes a feature which the R3 team have implemented only in their commercial product? How is this apparent conflict managed?
Our approach is simple: if the contribution meets the standards for the project (see above), then the existence of a competing commercial
implementation will not be used as a reason to reject it. In other words, it is our policy that should a community feature be contributed
which meets the criteria above, we will accept it or work with the contributor to merge/reconcile it with the commercial feature.
.. _`Corda introductory white paper`: _static/corda-platform-whitepaper.pdf

192
docs/source/contributing.rst
View File

@ -1,103 +1,102 @@
How to contribute
=================
.. contents::
Contribution guidelines
-----------------------
We believe one of the things that makes Corda special is its coherent design and we seek to retain this defining characteristic. From the
outset we defined some guidelines to ensure new contributions only ever enhance the project:
* **Quality**: Code in the Corda project should meet the :doc:`Corda coding style guidelines <codestyle>`, with sufficient test-cases,
descriptive commit messages, evidence that the contribution does not break any compatibility commitments or cause adverse feature
interactions, and evidence of high-quality peer-review
* **Size**: The Corda project's culture is one of small pull-requests, regularly submitted. The larger a pull-request, the more likely it
is that you will be asked to resubmit as a series of self-contained and individually reviewable smaller PRs
* **Scope**: We try to ensure the Corda project remains coherent and focused so we ask that the feature's scope is within the definition
specified in the `Corda Technical Whitepaper`_
* **Maintainability**: If the feature will require ongoing maintenance (eg support for a particular brand of database), we may ask you to
accept responsibility for maintaining this feature
* **Non-duplicative**: If the contribution duplicates features that already exist or are already in progress, you may be asked to work with
the project maintainers to reconcile this. As the major contributor to Corda, many employees of `R3 <https://r3.com>`_ will be working on
features at any given time. To avoid surprises and foster transparency,
`our Jira work tracking system is public <https://r3-cev.atlassian.net/projects/CORDA/summary>`_. If in doubt, reach out to one of the
:ref:`Community Maintainers <community-maintainers>`
Identifying an area to contribute
---------------------------------
There are two ways to identify an area where you can contribute to Corda:
There are several ways to identify an area where you can contribute to Corda:
* If there is a specific contribution you would like to make, you should first confirm whether the contribution is appropriate by reaching
out in the ``#contributing`` channel of the `Corda Slack <http://slack.corda.net/>`_ or contacting one of the
:ref:`Community Maintainers <community-maintainers>` directly
* Browse issues labelled as ``good first issue`` in the
* If you do not have a specific contribution in mind, you can browse issues labelled as ``help wanted`` 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 ``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)
* Ask in the ``#design`` channel of the `Corda Slack <http://slack.corda.net/>`_
* Issues that additionally have the ``good first issue`` label are considered ideal for first-timers
Making the required changes
---------------------------
You should make your changes as follows:
1. Create a fork of the master branch of the `Corda repo <https://github.com/corda/corda>`_
2. Clone the fork to your local machine
3. Build Corda by following the instructions :doc:`here </building-corda>`
4. Make the changes, in accordance with the :doc:`code style guide </codestyle>`
Extending the flow state machine
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can find instructions on how to extend the flow state machine :doc:`here </contributing-flow-state-machines>`
Things to check
^^^^^^^^^^^^^^^
Is your error handling up to scratch?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* **Make sure your error handling is 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
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
Look for API breaks
~~~~~~~~~~~~~~~~~~~
* **Suppress inevitable compiler warnings:** Compiler warnings should have a ``@Suppress`` annotation on them if they're expected and can't
be avoided
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.
* **Remove deprecated functionality:** When deprecating functionality, make sure you remove the deprecated uses in the codebase
Suppress inevitable compiler warnings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* **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
Compiler warnings should have a ``@Suppress`` annotation on them if they're expected and can't be avoided.
* **Things to consider when writing CLI apps:** Make sure any changes to CLI applications conform to the :doc:`cli-ux-guidelines`
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Make sure any changes to CLI applications conform to the :doc:`cli-ux-guidelines`.
Extending the flow state machine
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are interested in extending the flow state machine, you can find instructions on how to do this
:doc:`here </contributing-flow-state-machines>`.
Testing the changes
-------------------
You should test your changes as follows:
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.
1. **Add 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>`.
2. **Run 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.
3. **Perform 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 can test your changes against CorDapps defined in other repos by following the instructions
:doc:`here </building-against-master>`.
4. **Build against the master branch**: 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>`.
5. **Run 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:
You should document any changes to Corda's public API 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
@ -106,13 +105,14 @@ Any changes to Corda's public API must be documented as follows:
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.
4. :doc:`Build the docs locally </building-the-docs>` and check that the resulting .html files (under ``docs/build/html``) for the modified
render correctly
5. 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
-----------------------------------
You should merge the changes back into Corda as follows:
1. Create a pull request from your fork to the ``master`` branch of the Corda repo
@ -129,12 +129,64 @@ Merging the changes back into Corda
* 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)."
* 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://developercertificate.org/)."
4. Request a review from a member of the Corda platform team via the `#design channel <http://slack.corda.net/>`_
3. Request a review by reaching out in the ``#contributing`` channel of the `Corda Slack <http://slack.corda.net/>`_ or contacting one of
the :ref:`Community Maintainers <community-maintainers>` directly
5. The reviewer will either:
4. 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
* Leave comments requesting changes via the GitHub PR interface
* You should make the changes by pushing directly to your existing PR branch. The PR will be updated automatically
5. (Optional) Open an additional PR to add yourself to the
`contributors list <https://github.com/corda/corda/blob/master/CONTRIBUTORS.md>`_
* The format is generally ``firstname surname (company)``, but the company can be omitted if desired
Developer Certificate of Origin
-------------------------------
All contributions to this project are subject to the terms of the Developer Certificate of Origin, available
`here <https://developercertificate.org/>`_ and reproduced below::
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
.. _`Corda Technical Whitepaper`: _static/corda-technical-whitepaper.pdf

52
docs/source/testing.rst
View File

@ -1,41 +1,35 @@
Testing Corda
=============
Testing your changes
====================
Automated Tests
Automated tests
---------------
Corda has a suite of tests that any contributing developers must maintain and extend when adding new code.
Corda has a maintained suite of tests that any contributing developers must maintain and add to if new code has been added.
There are several test suites:
There are several distinct test suites each with a different purpose;
* **Unit tests**: These are traditional unit tests that should only test a single code unit, typically a method or class.
* **Integration tests**: These tests should test the integration of small numbers of units, preferably with mocked out services.
* **Smoke tests**: These are full end to end tests which start a full set of Corda nodes and verify broader behaviour.
* **Other**: These include tests such as performance tests, stress tests, etc, and may be in an external repo.
**Unit tests**: These are traditional unit tests that should only test a single code unit, typically a method or class.
Running the automated tests
^^^^^^^^^^^^^^^^^^^^^^^^^^^
These tests are mostly written with JUnit and can be run via ``gradle``:
**Integration tests**: These tests should test the integration of small numbers of units, preferably with mocked out services.
**Smoke tests**: These are full end to end tests which start a full set of Corda nodes and verify broader behaviour.
**Other**: These include tests such as performance tests, stress tests, etc, and may be in an external repo.
These tests are mostly written with JUnit and can be run via ``gradle``. On windows run ``gradlew test integrationTest
smokeTest`` and on unix run ``./gradlw test integrationTest smokeTest`` or any combination of these three arguments.
* **Windows**: Run ``gradlew test integrationTest smokeTest``
* **Unix/Mac OSX**: Run ``./gradlew test integrationTest smokeTest``
Before creating a pull request please make sure these pass.
Manual Testing
Manual testing
--------------
You should manually test anything that would be impacted by your changes. The areas that usually need to be manually tested and when are
as follows:
Manual testing would ideally be done for every set of changes merged into master, but practically you should manually test
anything that would be impacted by your changes. The areas that usually need to be manually tested and when are below;
* **Node startup** - changes in the ``node`` or ``node:capsule`` project in both the Kotlin or gradle or the ``cordformation`` gradle plugin.
* **Sample project** - changes in the ``samples`` project. eg; changing the IRS demo means you should manually test the IRS demo.
* **Explorer** - changes to the ``tools/explorer`` project.
* **Demobench** - changes to the ``tools/demobench`` project.
**Node startup** - changes in the ``node`` or ``node:capsule`` project in both the Kotlin or gradle or the ``cordformation`` gradle plugin.
**Sample project** - changes in the ``samples`` project. eg; changing the IRS demo means you should manually test the IRS demo.
**Explorer** - changes to the ``tools/explorer`` project.
**Demobench** - changes to the ``tools/demobench`` project.
How to manually test each of these areas differs and is currently not fully specified. For now the best thing to do is
ensure the program starts, that you can interact with it, and that no exceptions are generated in normal operation.
TODO: Add instructions on manual testing
How to manually test each of these areas differs and is currently not fully specified. For now the best thing to do is to ensure the
program starts, that you can interact with it, and that no exceptions are generated in normal operation.