How to contribute

How to contribute Code or Documentation on GitHub

Frequently Asked Questions about contributing

What branch should I push to?

There are always two main branches in GeoNetwork: a stable and an unstable one.

• The stable one is the latest branch with the name \$version.\$minor.x.
• The unstable branch is the branch called master.

You have to do the PR on master. See more about this in Branches.

Should I do a direct PR or commit?

Use Pull Requests even if you can push directly, so the tests are run and other developers can check your code before it gets merged.

How should my PR be to get accepted?

For your Pull Request to be accepted, please follow the Contributing Guidelines.

Pull Request Housekeeping

Anytime you commit something, try to clean the code around it to adapt to latest guide styles rules. If you improve a function without comments, add comments to it. If you modify a functionality without unit tests, create some unit testing around it. If you fix a functionality not described on the documentation, add at least a small description about it or improve current documentation.

Pull Request clean commit messages and history

• Avoid big commits with hundreds of files, try to break commits into understandable things.

• Avoid empty or non-relevant commit messages like "bug fix" or "improvement". Always be as explicit as possible on commit messages, even if you are planning on writing a long documentation on the Pull Request afterward.

• Try to be as verbose as possible when describing what your code is doing in commit messages, comments, variable naming, function naming, etcetera. Better to have duplicated documentation than none.

• If you know that one of the commits in your PR is not consistent or can break some functionality, please specify at the beginning of the commit message "WIP" (Work In Progress).

• If one of your commits has an impact on API behavior, please specify in the commit message the signatures. Also make sure the Process of Deprecation has been followed with care!

No merge commits with current branch

If you are pulling from the official branch to your own branch, always rebase. Never do a merge commit. Remember that you can push --force to the branch you are working in to avoid merge messages.

Pull Request Review and acceptance?

For a PR to be accepted, it has to be reviewed at least by another person other than you. Better if more than one person can review it. Don’t be shy of asking for help or reviewing.

Pull Request Testing

All new features or enhancements should have automatic tests.

Pull Request User Documentation

All new features or enhancements should have documentation, both on the source code and on the official documentation

Please review the documentation guide for writing guidelines and Markdown use.

Pull Request Developer Documentation

Changes to the development or build environment require update to the software development documentation included in repository the README.md files.

The addition of a new tool, library or dependency is an example of such a change covered next.

Pull Request adding new tools, libraries or dependencies

If you are adding a new library or dependency to GeoNetwork:

• Use the root pom.xml dependencyManagement section to define the dependency and version number

• Document the new library (or point to any existing external documentation) that cover:

• What the library does in the scope of GeoNetwork

• How it interacts with GeoNetwork or how to extend the current usage on GeoNetwork

• Pointer to official library tutorials or documentation

Documentation is added to the software development documentation included in repository the README.md files:

• Overview

• Tools

• Individual modules:

  • ElasticSearch

  • JCloud Data storage

I created a Pull Request, what now?

You have to wait for a review first and merging later. Please, be quick answering reviewers comments and doing the requested changes. Pull Requests with requested changes or questions will be closed after a few months of inactivity.

In the meantime, if you actively review other open pull requests, even if you have not been explicitly asked to review, that will lower the amount of reviewing work from the core developer group, making your pull request closer to review.

How can I review a pull-request?

There are three basic steps to review:

• Readability and Style: Make sure the code follows the standards and is legible and understandable. Understand what it does and suggest improvements, if any.

• Automated tests: GitHub Actions should run automated tests, please double check they passed.

  To run locally checkout the branch on a clean folder ("_git clean -fxxd_" can help), build and compile it with "_mvn clean package install_". Warn if any test does fail.
  

• Manual testing: Deploy it with "cd web;mvn jetty:run" and test the functionality. Warn if something is broken.

  Use the documentation included with the pull-request to identify the user interface changes needing manual testing.
  

After each step, comment on the Pull Request that you made that step and the result, even if it is a success.