Difference between revisions of "Contributing to Eigen"

From Eigen
Jump to: navigation, search
(Documentation: requiring user name for wiki access)
 
(9 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
== Support ==
 
== Support ==
  
Perhaps the easiest way to help is to be willing to support new (and not so new) users of Eigen and answer their questions. People ask questions on the [http://forum.kde.org/viewforum.php?f=74 forum], on IRC (#eigen on [irc://irc.freenode.net irc.freenode.net]), on the [[Main Page#Mailing list|mailing list]]. There may also be questions on websites not connected to the project such as StackOverflow.
+
Perhaps the easiest way to help is to be willing to support new (and not so new) users of Eigen and answer their questions. People ask questions on the [https://stackoverflow.com/questions/tagged/eigen+or+eigen3 StackOverflow], on [[Main Page#Discord Server| Discord]] or on the [[Main Page#Mailing list|mailing list]]. You can also improve our [[FAQ]] with questions (and answers) that arise frequently.
You can also improve our [[FAQ]] with questions (and answers) that arise frequently.
+
  
 
Users arrive with different levels of C++ and mathematics knowledge, so whatever your level of experience, you can help out with this. Do not be too worried about given wrong advice; if you are not sure that your answer is correct, just say you are not sure and others will jump in if necessary.
 
Users arrive with different levels of C++ and mathematics knowledge, so whatever your level of experience, you can help out with this. Do not be too worried about given wrong advice; if you are not sure that your answer is correct, just say you are not sure and others will jump in if necessary.
Line 12: Line 11:
 
In common with almost all software projects, we are struggling with writing good documentation, so we are especially keen to get help in this area. It might actually help here if you do not have years of experience with Eigen, as that makes you more in tune with the people that are reading the documentation. After answering users' questions, as explained above, think about whether the current documentation could be improved so that the question would not have arisen. This is not always possible, but questions often point to shortcomings in our documentation.
 
In common with almost all software projects, we are struggling with writing good documentation, so we are especially keen to get help in this area. It might actually help here if you do not have years of experience with Eigen, as that makes you more in tune with the people that are reading the documentation. After answering users' questions, as explained above, think about whether the current documentation could be improved so that the question would not have arisen. This is not always possible, but questions often point to shortcomings in our documentation.
  
Most of the documentation resides at http://eigen.tuxfamily.org/dox (or http://eigen.tuxfamily.org/dox-devel for the branch currently in development) and is generated by doxygen from comments in the source code (see [[Developer's Corner#Documentation tips]]). You can submit patches as described below. If your change is not too massive, an alternative is to use the web interface at bitbucket: fork the Eigen code at https://bitbucket.org/eigen/eigen, find the correct source file, edit it, and submit a merge request to have your changes included.
+
Most of the documentation resides at https://eigen.tuxfamily.org/dox (or https://eigen.tuxfamily.org/dox-devel for the branch currently in development) and is generated by Doxygen from comments in the source code (see [[Developer's Corner#Documentation tips]]).
  
There is also some documentation on this wiki and you are welcome to add to this. You can also use the wiki as a staging ground for documentation to be included in doxygen. If you do not have an account to the wiki, ask one of the [http://eigen.tuxfamily.org/index.php?title=Special:ListUsers&group=sysop administrators] (please write the user name you want to have and perhaps briefly what you want to edit or add).
+
There is also some documentation on this wiki and you are welcome to add to this. You can also use the wiki as a staging ground for documentation to be included in Doxygen. If you do not have an account to the wiki, ask one of the [http://eigen.tuxfamily.org/index.php?title=Special:ListUsers&group=sysop administrators] (please write the user name you want to have and perhaps briefly what you want to edit or add).
  
 
== Bugs: triage, discussion, fixing ==
 
== Bugs: triage, discussion, fixing ==
  
If you discover a bug, please [[Bugzilla#Reporting_a_bug|report it]]! If you are unsure if it is a bug, you can ask on IRC or the mailing list first.
+
If you discover a bug, please [[Bugzilla#Reporting_a_bug|report it]]! If you are unsure if it is a bug, you can ask on Discord or the mailing list first.
  
As of June 2014 there are [http://eigen.tuxfamily.org/bz/buglist.cgi?bug_status=__open__ more than 300 open bugs]! It is hard to keep on top of them so any help in maintaining the list is very useful. The first step is to try and reproduce the bug. You may have to ask the bug reporter for information on the version of Eigen, the compiler, the OS, etc. Set the severity field to the correct value. Add keywords if necessary (you can suggest additional keywords on the mailing list).
+
As of February 2021 there are [https://gitlab.com/libeigen/eigen/-/issues almost 600 open bugs]! It is hard to keep on top of them so any help in maintaining the list is very useful. The first step is to try and reproduce the bug. You may have to ask the bug reporter for information on the version of Eigen, the compiler, the OS, etc.
Also, if you can reproduce a bug or if you support a feature request, change its status from NEW or UNCONFIRMED to CONFIRMED (or DECISIONNEEDED, see next paragraph).
+
Eventually, we will drop all [http://eigen.tuxfamily.org/bz/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW NEW and UNCONFIRMED bugs] (we have not decided on a deadline for that).
+
  
For bugs having the [http://eigen.tuxfamily.org/bz/buglist.cgi?bug_status=DECISIONNEEDED DECISIONNEEDED status] there is either no agreement if they shall be fixed; or they are  
+
For some bugs (usually marked with the [https://gitlab.com/libeigen/eigen/-/issues?label_name%5B%5D=decision+needed "decision needed" label]) there is either no agreement if they shall be fixed; or they are  
 
acknowledged but different approaches to solve them exist, which might lead to different APIs or behavior. You are welcome to take part in these discussions!
 
acknowledged but different approaches to solve them exist, which might lead to different APIs or behavior. You are welcome to take part in these discussions!
If we feel that a discussion has settled, we'll announce it on the mailing list (giving a possibility to object) and afterwards change the status to CONFIRMED.
 
  
 
If you have an idea what might cause a bug or how it possibly could be fixed, add a comment to the corresponding bug-entry.
 
If you have an idea what might cause a bug or how it possibly could be fixed, add a comment to the corresponding bug-entry.
 
If you exactly know how to fix a bug, please send us a patch or a pull request. See our [[Mercurial]] page for details on that.
 
If you exactly know how to fix a bug, please send us a patch or a pull request. See our [[Mercurial]] page for details on that.
 
Also [[Tests#Writing_unit_tests|add a unit test]] to avoid regressions on particular bugs.
 
Also [[Tests#Writing_unit_tests|add a unit test]] to avoid regressions on particular bugs.
In principle, [http://eigen.tuxfamily.org/bz/buglist.cgi?keywords=JuniorJob&resolution=--- searching bugzilla for bugs with the JuniorJob keyword] will give you a list of open bugs which do not require deep understanding of Eigen's internals, yet in some cases might require expertise in different areas.
+
In principle, [https://gitlab.com/libeigen/eigen/-/issues?label_name%5B%5D=junior+job searching GitLab for bugs with the "junior job" label] will give you a list of open bugs which do not require deep understanding of Eigen's internals, yet in some cases might require expertise in different areas.
 
Usage of this keyword will hopefully grow in the future.
 
Usage of this keyword will hopefully grow in the future.
  
Line 39: Line 35:
  
 
If you have CPU hours to spare you can make nightly runs of our [[Tests|testsuite]]. This would be especially helpful for rarely tested compilers (of course, some redundancy is appreciated here as well).
 
If you have CPU hours to spare you can make nightly runs of our [[Tests|testsuite]]. This would be especially helpful for rarely tested compilers (of course, some redundancy is appreciated here as well).
See our [http://manao.inria.fr/CDash/index.php?project=Eigen Dashboard] for platforms and configurations that are tested at the moment.
+
See our [https://my.cdash.org/index.php?project=Eigen Dashboard] for platforms and configurations that are tested at the moment.
  
 
Writing unit tests and documentation for one of the unsupported modules might be the task with the smoothest learning curve.
 
Writing unit tests and documentation for one of the unsupported modules might be the task with the smoothest learning curve.
Line 45: Line 41:
 
== Discussing API and overall design ==
 
== Discussing API and overall design ==
  
From time to time there are discussions on the mailing list or in bugzilla about new features or change requests in the current API. It helps to get feedback from actual users on what kind of API they expect.  
+
From time to time there are discussions on the mailing list or on GitLab about new features or change requests in the current API. It helps to get feedback from actual users on what kind of API they expect.  
  
 
Taking part in these discussions does not require being able to implement those changes!
 
Taking part in these discussions does not require being able to implement those changes!
Line 51: Line 47:
 
== Contributing code ==
 
== Contributing code ==
  
If you have code to contribute (be it documentation or bug fixes or new features), then submit it either as a patches on bugzilla or as a merge request on bitbucket. See the page on [[Mercurial]] for how to produce a patch or a merge request and see the [[Developer's Corner]] for some general advice. Code implementing new features should have reached a certain standard before we can accept them; in particular, we expect the code to include tests and documentation. If your patch or merge is being ignored, don't be shy to remind us of it.
+
If you have code to contribute (be it documentation or bug fixes or new features), then submit it as a merge request on [https://gitlab.com/libeigen/eigen GitLab]. See the page on [[Git]] for how to produce a patch or a merge request and see the [[Developer's Corner]] for some general advice. Code implementing new features should have reached a certain standard before we can accept them; in particular, we expect the code to include tests and documentation. If your patch or merge is being ignored, don't be shy to remind us of it.
  
 
Unfortunately, some of the current code is not explained as clearly as we would like, especially the internal and the more complicated parts. Hopefully this will improve over time. The [[publications]], especially the slides from Eurographics/CGLibs in Pisa, may help to gain an overview of the architecture. Do not hesitate to ask for help on the mailing list or IRC, or contact one of the [[#Volunteers|volunteers]] listed below. If you do not understand it, chances are other people will also not understand it, so do improve the code or the documentation once you get it.
 
Unfortunately, some of the current code is not explained as clearly as we would like, especially the internal and the more complicated parts. Hopefully this will improve over time. The [[publications]], especially the slides from Eurographics/CGLibs in Pisa, may help to gain an overview of the architecture. Do not hesitate to ask for help on the mailing list or IRC, or contact one of the [[#Volunteers|volunteers]] listed below. If you do not understand it, chances are other people will also not understand it, so do improve the code or the documentation once you get it.
Line 58: Line 54:
 
Also if your contribution involves major API decisions, it is generally advantageous to discuss them first.
 
Also if your contribution involves major API decisions, it is generally advantageous to discuss them first.
  
== Volunteers ==
+
'''Notice: If you own a fork that was severed from the main GitLab repo by the accidental deletion on October 2nd 2021, you can re-establish the fork relationship by following the [https://eigen.tuxfamily.org/index.php?title=Reforking_the_GitLab_Project instructions here].'''
 
+
This section is to collect people who would like to regularly contribute to Eigen.
+
If you intend to regularly contribute to Eigen, add yourself to this table.
+
Add areas of interest, expertise, or anything else in the second column. This could be structured better in the future.
+
 
+
If you don't have write access to this wiki, ask an [http://eigen.tuxfamily.org/index.php?title=Special:ListUsers&group=sysop administrator].
+
 
+
{| class="wikitable" border="1"  cellpadding="4"
+
!Name
+
!Interests
+
|-
+
| Christoph Hertzberg
+
| API and Architecture Discussions, Reviewing patches, ...
+
|-
+
| Jitse Niesen
+
| Dense linear algebra, Reviewing patches, Documentation ...
+
|-
+
| Christian Seiler
+
| Tensor module, API and Architecture Discussions, Advanced and modern C++, Obscure algorithms ...
+
|-
+
|}
+
 
+
[[Category:Developer]]
+

Latest revision as of 16:39, 27 October 2021

Eigen is written and maintained by volunteers. If you are willing to help, great! Here are some pointers to get you started.

Support

Perhaps the easiest way to help is to be willing to support new (and not so new) users of Eigen and answer their questions. People ask questions on the StackOverflow, on Discord or on the mailing list. You can also improve our FAQ with questions (and answers) that arise frequently.

Users arrive with different levels of C++ and mathematics knowledge, so whatever your level of experience, you can help out with this. Do not be too worried about given wrong advice; if you are not sure that your answer is correct, just say you are not sure and others will jump in if necessary.

Documentation

In common with almost all software projects, we are struggling with writing good documentation, so we are especially keen to get help in this area. It might actually help here if you do not have years of experience with Eigen, as that makes you more in tune with the people that are reading the documentation. After answering users' questions, as explained above, think about whether the current documentation could be improved so that the question would not have arisen. This is not always possible, but questions often point to shortcomings in our documentation.

Most of the documentation resides at https://eigen.tuxfamily.org/dox (or https://eigen.tuxfamily.org/dox-devel for the branch currently in development) and is generated by Doxygen from comments in the source code (see Developer's Corner#Documentation tips).

There is also some documentation on this wiki and you are welcome to add to this. You can also use the wiki as a staging ground for documentation to be included in Doxygen. If you do not have an account to the wiki, ask one of the administrators (please write the user name you want to have and perhaps briefly what you want to edit or add).

Bugs: triage, discussion, fixing

If you discover a bug, please report it! If you are unsure if it is a bug, you can ask on Discord or the mailing list first.

As of February 2021 there are almost 600 open bugs! It is hard to keep on top of them so any help in maintaining the list is very useful. The first step is to try and reproduce the bug. You may have to ask the bug reporter for information on the version of Eigen, the compiler, the OS, etc.

For some bugs (usually marked with the "decision needed" label) there is either no agreement if they shall be fixed; or they are acknowledged but different approaches to solve them exist, which might lead to different APIs or behavior. You are welcome to take part in these discussions!

If you have an idea what might cause a bug or how it possibly could be fixed, add a comment to the corresponding bug-entry. If you exactly know how to fix a bug, please send us a patch or a pull request. See our Mercurial page for details on that. Also add a unit test to avoid regressions on particular bugs. In principle, searching GitLab for bugs with the "junior job" label will give you a list of open bugs which do not require deep understanding of Eigen's internals, yet in some cases might require expertise in different areas. Usage of this keyword will hopefully grow in the future.

We need support especially for rarely used compilers and platforms!

Testing

If you have CPU hours to spare you can make nightly runs of our testsuite. This would be especially helpful for rarely tested compilers (of course, some redundancy is appreciated here as well). See our Dashboard for platforms and configurations that are tested at the moment.

Writing unit tests and documentation for one of the unsupported modules might be the task with the smoothest learning curve.

Discussing API and overall design

From time to time there are discussions on the mailing list or on GitLab about new features or change requests in the current API. It helps to get feedback from actual users on what kind of API they expect.

Taking part in these discussions does not require being able to implement those changes!

Contributing code

If you have code to contribute (be it documentation or bug fixes or new features), then submit it as a merge request on GitLab. See the page on Git for how to produce a patch or a merge request and see the Developer's Corner for some general advice. Code implementing new features should have reached a certain standard before we can accept them; in particular, we expect the code to include tests and documentation. If your patch or merge is being ignored, don't be shy to remind us of it.

Unfortunately, some of the current code is not explained as clearly as we would like, especially the internal and the more complicated parts. Hopefully this will improve over time. The publications, especially the slides from Eurographics/CGLibs in Pisa, may help to gain an overview of the architecture. Do not hesitate to ask for help on the mailing list or IRC, or contact one of the volunteers listed below. If you do not understand it, chances are other people will also not understand it, so do improve the code or the documentation once you get it.

If you plan to make bigger contributions, first ask if anyone else is working on that or something related in order to reduce duplicated efforts. Also if your contribution involves major API decisions, it is generally advantageous to discuss them first.

Notice: If you own a fork that was severed from the main GitLab repo by the accidental deletion on October 2nd 2021, you can re-establish the fork relationship by following the instructions here.