Skip to content

Latest commit

 

History

History
executable file
·
121 lines (101 loc) · 6.25 KB

CONTRIBUTING.md

File metadata and controls

executable file
·
121 lines (101 loc) · 6.25 KB
Raw

Contributing to AVNI

AVNI is a community project that lives by the participation of its members — i.e., including you! It is our goal to build an inclusive and participatory community so we are happy that you are interested in participating!

Getting started with git and GitHub

If you are new to using git or the GitHub platform, you should start by taking one of the many freely available git tutorials (for an excellent medium depth tutorial see: http://swcarpentry.github.io/git-novice/). Additionally, GitHub provides a helpful guide on the process of managing a github project: https://guides.github.com/introduction/flow/.

Asking and answering questions about AVNI

For questions about AVNI on all levels, please use the AVNI forum.

Bug reports

It is a great help to the community if you report any bugs that you may find. We keep track of all open issues related to AVNI here.

Please follow these simple instructions before opening a new bug report:

  • Do a quick search in the list of open and closed issues for a duplicate of your issue.
  • If you did not find an answer, open a new issue and explain your problem in as much detail as possible.
  • Attach as much as possible of the following information to your issue:
    • a minimal setup that reproduces the issue,
    • the model output that was created during the model run,
    • the error message you saw on your screen,
    • any information that helps us understand why you think this is a bug, and how to reproduce it.

Making AVNI better

AVNI is a community project, and we are encouraging all kinds of contributions. The governance of the project is descibed on the docs website.

If you consider making a larger contribution to the core functionality, please open a new issue first, to discuss your idea with one of the maintainers. This allows us to give you early feedback and prevents you from spending much time on a project that might already be planned, or that conflicts with other plans.

To make a change to AVNI you should:

  • Create a fork (through GitHub) of the code base.
  • Create a separate branch (sometimes called a feature branch) on which you do your modifications.
  • You can propose that your branch be merged into the AVNI code by opening a pull request. This will give others a chance to review your code.

We follow the philosophy that no pull request (independent of the author) is merged without a review from one other member of the community, and approval of one of the maintainers. This applies to maintainers as well as to first-time contributors. We know that a review can be a daunting process, but pledge to keep all comments friendly and supportive. We are as interested in making AVNI better as you are!

While this seems very formal, keeping all of the code review in one place makes it easier to coordinate changes to the code (and there are usually several people making changes to the code at once). Please do not hesitate to ask questions about the workflow on the forum if you are not sure what to do.

We follow certain coding conventions that are described in the Contributing guide. New contributors can set up their machine to follow these coding conventions.

If you are new to the project then we will work with you to ensure your contributions are formatted with this style, so please do not think of it as a road block if you would like to contribute some code.

Acknowledgment of contributions

While we are grateful for every contribution, there are also several official ways your contribution will be acknowledged by the AVNI community:

  • Every commit that was merged into the AVNI repository will make you part of the growing group of AVNI contributors.

  • Mention through any other kind of attribution the project provides (e.g. newsletters, release papers, manual authorship).

  • Regularly, the Principal Developers of AVNI come together and discuss based on the contributions of the last years who should be invited to join the group of Principal Developers. Criteria that Principal Developers should match are:

  • A profound understanding of AVNI's structure and vision,

  • A proven willingness to further the project's goals and help other users,

  • Significant contributions to AVNI (not necessarily only source code, also mailing list advice, documentation, benchmarks, tutorials),

  • Regular and active contributions to AVNI for more than one year, not restricted to user meetings.

The group of current Principal Developers is listed in the AUTHORS file in the main repository.

Further reading

  • Contributing guide: The standard way of contributing to AVNI development is described here. To create a product that is maintainable over the long term, it is important that contributing scientists follow these conventions. This approach is recommended for most users, especially those not familiar with Git. These instructions are adequate for contributing to AVNI, but we recommend that all new users to Git attempt the tutorial below for more complete understanding of the workflow.

  • Software Carpentry Git Tutorial: For those who are not familiar with Git, we recommend attempting this tutorial, or even better, attending an in-person tutorial session if available in your area.

License

AVNI is published under the GNU GENERAL PUBLIC LICENSE; while you will retain copyright on your contributions, all changes to the code must be provided under this common license. A copy of this LICENSE is provided in the AVNI Github repository