This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

How to contribute

    Getting the source code

    First of all, you need the Avro source code.

    The easiest way is to clone or fork the GitHub mirror:

    git clone https://github.com/apache/avro.git -o github

    Making Changes

    Before you start, file an issue in JIRA or discuss your ideas on the Avro developer mailing list. Describe your proposed changes and check that they fit in with what others are doing and have planned for the project. Be patient, it may take folks a while to understand your requirements.

    Modify the source code and add some (very) nice features using your favorite IDE.

    But take care about the following points

    All Languages

    • Contributions should pass existing unit tests.
    • Contributions should document public facing APIs.
    • Contributions should add new tests to demonstrate bug fixes or test new features.

    Java

    • All public classes and methods should have informative Javadoc comments.
    • Do not use @author tags.
    • Java code should be formatted according to Oracle’s conventions, with one exception:
      • Indent two spaces per level, not four.
    • JUnit is our test framework:
    • You must implement a class whose class name starts with Test.
    • Define methods within your class and tag them with the @Test annotation. Call JUnit’s many assert methods to verify conditions; these methods will be executed when you run mvn test.
    • By default, do not let tests write any temporary files to /tmp. Instead, the tests should write to the location specified by the test.dir system property.
    • Place your class in the src/test/java/ tree.
    • You can run all the unit tests with the command mvn test, or you can run a specific unit test with the command mvn -Dtest=<class name, fully qualified or short name> test (for example mvn -Dtest=TestFoo test)

    Code Style (Autoformatting)

    For Java code we use Spotless to format the code to comply with Avro’s code style conventions (see above). Automatic formatting relies on Avro’s Eclipse JDT formatter definition. You can use the same definition to auto format from Eclipse or from IntelliJ configuring the Eclipse formatter plugin.

    If you use maven code styles issues are checked at the compile phase. If your code breaks because of bad formatting, you can format it automatically by running the command:

    mvn spotless:apply

    Unit Tests

    Please make sure that all unit tests succeed before constructing your patch and that no new compiler warnings are introduced by your patch. Each language has its own directory and test process.

    Java
    cd avro-trunk/lang/java
mvn clean test
    Python
    cd avro-trunk/lang/py
./setup.py build test
    Rust
    cd avro-trunk/lang/rust
./build.sh clean test
    C#
    cd avro-trunk/lang/csharp
./build.sh clean test
    C
    cd avro-trunk/lang/c
./build.sh clean
./build.sh test
    C++
    cd avro-trunk/lang/c++
./build.sh clean test
    Ruby
    cd avro-trunk/lang/ruby
gem install echoe
rake clean test
    PHP
    cd avro-trunk/lang/php
./build.sh clean
./build.sh test

    Contributing your code

    Contribution can be made directly via github with a Pull Request, or via a patch.

    Via Github

    Method is to create a pull request.

    On your fork, create a branch named with JIRA (avro-1234_fixNpe for example) On source, go to it

    git pull
git switch avro-1234_fixNpe

    code your changes (following preceding recommendations)

    check and add updated sources

    git status

# Add any new or changed files with:
git add src/.../MyNewClass.java
git add src/.../TestMyNewClass.java

    Finally, create a commit with your changes and a good log message, and push it:

    git commit -m "AVRO-1234: Fix NPE by adding check to ..."
git push

    On your github fork site, a button will propose you to build the Pull Request. Click on it, fill Conversation form, and create it. Link this PR to the corresponding JIRA ticket (on JIRA ticket, add PR to “Issue Links” chapter, and add label ‘pull-request-available’ to it .

    Jira Guidelines

    Please comment on issues in Jira, making your concerns known. Please also vote for issues that are a high priority for you.

    Please refrain from editing descriptions and comments if possible, as edits spam the mailing list and clutter Jira’s “All” display, which is otherwise very useful. Instead, preview descriptions and comments using the preview button (on the right) before posting them. Keep descriptions brief and save more elaborate proposals for comments, since descriptions are included in Jira’s automatically sent messages. If you change your mind, note this in a new comment, rather than editing an older comment. The issue should preserve this history of the discussion.

    Stay involved

    Contributors should join the Avro mailing lists. In particular, the commit list (to see changes as they are made), the dev list (to join discussions of changes) and the user list (to help others).

    Workflow

    Building and running the site locally requires a recent extended version of Hugo. Install Hugo for your environment. Once you’ve made your working copy of the site repo, from the repo root folder, run:

    hugo server --navigateToChanged

    Edit .md and .html files in content/ folder

    Once satisfied with the changes, commit them:

    git commit -a

    Generate the HTML file stop hugo server –navigateToChanged (with Ctrl+C) and run

    hugo

    This will generate the HTMLs in public/ folder and this is actually what is being deployed

    Add the modified HTML files to Git

    git add .
git rm offline-search-index.<<OLD-HASH>>.json
git commit -a
git push

    This way even when the PR modifies a lot of files we can review only the first commit, the meaningful one, with the modified files in content/ folder

    Running a container locally

    You can also run avro-website inside a Docker container, the container runs with a volume bound to the avro-website folder. This approach doesn’t require you to install any dependencies other than Docker Desktop on Windows and Mac, and Docker Compose on Linux.

    Build the docker image

    docker-compose build

    Run the built image

    docker-compose up

    NOTE: You can run both commands at once with docker-compose up –build.

    Verify that the service is working.

    Open your web browser and type http://localhost:1313 in your navigation bar, This opens a local instance of the docsy-example homepage. You can now make changes to the docsy example and those changes will immediately show up in your browser after you save.

    Cleanup

    To stop Docker Compose, on your terminal window, press Ctrl + C.

    To remove the produced images run:

    docker-compose rm

    Troubleshooting

    As you run the website locally, you may run into the following error:

    ➜ hugo server

INFO 2021/01/21 21:07:55 Using config file: 
Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
Built in 288 ms
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache

    This error occurs if you have not installed the extended version of Hugo. See our user guide for instructions on how to install Hugo.

    Edit content

    The website content is in content/en folder. It contains .md (Markdown) and .html (HTML) files.

    Layouts

    To change the layout of any page edit layouts//**.html. If there is no layout for a given page at that location then copy the one provided by the theme and edit it:

    cp themes/docsy/layouts/<xyz> layouts/<xyz>

    Avro version

    When a new version of Apache Avro is released:

    Change the value of params.avroversion in config.toml Add a new entry to the Releases pages in the Blog section, for example:

    cp content/en/blog/releases/avro-1.10.2-released.md content/en/blog/releases/avro-1.11.0-released.md

    API documentation for C/C++/C# modules

    The API documentations for C/C++/C# are built by their respective build.sh dist implementations. The final HTML should be copied to the external folder, for example:

    cp ../avro/build/avro-doc-1.12.0-SNAPSHOT/api/c/* content/en/docs/external/c/

    JIRA conventions

    Issue types: JIRA issues are categorized into different types such as bugs, improvements, new features, etc. Each issue type has a unique icon and a set of fields that are specific to that type.

    Workflow: JIRA issues follow a predefined workflow that defines the steps that an issue goes through from creation to resolution. Each step in the workflow can have its own set of conditions and actions.

    Priority: JIRA allows users to set priorities for issues to help determine the order in which they should be addressed. The priority can be set to one of five levels: Blocker, Critical, Major, Minor, and Trivial. Blocker is the highest priority and Trivial is the lowest priority.

    Labels: Labels are used to tag issues with keywords or phrases that can help with searching and filtering.

    Components: Components are used to group related issues together. For example, a software project might have components for the user interface, database, and networking.

    See Also