////
Copyright (c) 2024 The C++ Alliance, Inc. (https://cppalliance.org)

Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Official repository: https://github.com/boostorg/website-v2-docs
////
= Getting Involved
:navtitle: Getting Involved

There are many ways to get involved with Boost, up to and including submitting your own library. In roughly ascending order of time and work commitment, here are the ways you can contribute to Boost:

[square]
* <<Participate in the Boost Developers Mailing List>>
* <<Report Issues and Suggest Improvements>>
** <<To Report an Issue with a Library>>
** <<To Report an Issue with an Outside Source>>
** <<To Report an Issue with this Website>>
* <<Engage in the Review Process>>
* <<Contribute to an Existing Library>>
* <<Maintain an Existing Library>>
* <<Contribute a New Library>>

== Participate in the Boost Developers Mailing List

The Boost mailing list is a platform for discussions and communications related to the Boost Libraries. The mailing list serves several key purposes:

* *Announcements*: The mailing list is a channel for updates, announcements about new releases, bug fixes, events, or any other relevant news.

* *Collaboration*: The mailing list also serves as a platform for collaboration, fostering connections between developers and encouraging team-based projects.

* *Discussion*: Developers discuss ideas, techniques, issues, and potential improvements related to Boost libraries.

* *Support*: Newcomers or users encountering difficulties can seek help from the community. Experienced members provide solutions, advice, and share their experiences.

If you do join, follow the xref:user-guide:ROOT:discussion-policy.adoc[] of the mailing list, as it helps in maintaining a respectful and productive environment.

To subscribe to the Developers Mailing List go https://lists.boost.org/mailman/listinfo.cgi/boost[Boost developers' mailing list].

There are other mailing lists you might want to join, such as the https://lists.boost.org/mailman/listinfo.cgi/boost-users[Boost Users mailing list], or project-specific lists. Visit https://www.boost.org/community/groups.html[Boost Mailing Lists] for more details.

== Report Issues and Suggest Improvements

There are different locations to report issues, depending on which content needs updated.

=== To Report an Issue with a Library

To formally report an issue on an individual library, locate the repo for that library. Many of these repos exist in the https://github.com/cppalliance/boost/tree/master/libs[Boost Super-project] on GitHub. Search under the `libs` folder. For example, to file an issue on the boost:json[] library, click *New Issue* at https://github.com/boostorg/json/issues[]. If you have difficulty locating the correct repo, then ask the question of the https://lists.boost.org/mailman/listinfo.cgi/boost[Boost developers' mailing list].

Before filing an issue, it is good practice to identify the admins (authors or maintainers) of a library. This information can be found in the `meta` folder for the library. For example: https://github.com/boostorg/json/blob/develop/meta/libraries.json[] contains the authors for the boost:json[] library. Also, library documentation and commit history may well specify who is actively involved. Make a connection first to ensure the library admins are open to updates.

Whichever list you add your issue to, the issue will be triaged and addressed appropriately. Providing full details, examples and screenshots where appropriate, should give you a quicker response.

=== To Report an Issue with an Outside Source

There are sources of information on the Boost libraries outside of this website and the library documentation, including:

* https://en.wikipedia.org/wiki/Boost_(C%2B%2B_libraries)[The Wikipedia page]
* https://www.linkedin.com/company/boostlibs/[The LinkedIn page]
* https://stackoverflow.com/questions/tagged/boost[Stack Overflow: Boost]

If you notice content that needs updated in these sources, perhaps out-of-date information, incorrect or missing information, or perhaps just language that could be improved, then complete the same process as *To Report an Issue with this Website*. Feedback like this is welcome.

[[createnewissue]]
=== To Report an Issue with this Website

To report an issue with the website, including this documentation, click the *New Issue* button on GitHub page: https://github.com/boostorg/website-v2-docs/issues[website-v2-docs/issues]. 

After clicking *New Issue*, you will be able to add a *Title* and *Description*. Provide as much detail as possible, including links where helpful and suggestions for the updated content.

== Engage in the Review Process

All libraries are reviewed by the community before becoming part of Boost. There are several roles in the review process, from managing the steps of the review process, to testing and providing feedback.  Read the xref:formal-reviews:ROOT:index.adoc[] for details.

[#contribute]
== Contribute to an Existing Library

Rather than report an issue, or suggested improvement, and wait for another developer to address it, you can make the code changes yourself (after verifying with the library admins that they are open to updates). To be successful you will need to be familiar with GitHub, and obviously a competent pass:[C++] developer. After finding the issue, you will need to go to the GitHub repository for that library, and create a fork and clone the library.

With your fork of the library in your own GitHub account, you can make any changes and updates you wish. It is certainly recommended to thoroughly test the changes, and be aware of the test matrix for the library. It is also recommended you thoroughly comment your code changes, potentially every line of code you add should be commented as to its purpose.

When you are satisfied you have met the bar for testing, you can commit the changes, push them to GitHub, and create a Pull Request. Most libraries have Continuous Integration (CI) set up, and will check your changes on several operating systems and compilers. If CI is not set up, there will be more onus on you and your testers to verify the test matrix.

After this, you can take a step back, and the owners or maintainers of the library will review your code. They might ask for some modifications or improvements. Incorporate the feedback provided by the reviewers and push your modifications.

If all goes well, your changes will be merged by the library admins, and you will have made a welcome contribution.

== Maintain an Existing Library

There may be an existing library that you have a deep interest in, that for some reason no longer has an active owner or maintainer. Or, perhaps, is being less well maintained than might be ideal. Find what you can out by asking questions of the existing maintainers (listed in the xref:requirements/library-metadata.adoc[] json file) and, if no reply, on the https://lists.boost.org/mailman/listinfo.cgi/boost[Boost developers' mailing list]. If the replies suggest you could take a role, consider requesting, again via the mailing list, to become a library maintainer. For larger libraries there can certainly be more than one maintainer. 

Maintaining an existing library is similar in steps to <<Contribute to an Existing Library>>, in that you will have to create a fork and clone the library. However, more is expected. You will have to spend time educating yourself on the full functionality of the library, and be prepared to make changes to the code anywhere changes are needed. 

For a larger library this education can turn out to be a significant, and perhaps onerous task. It can be quite difficult to reverse engineer in your mind the processes and purpose of code written by another developer, with all the expected personal style and idiosyncrasies that make their way into source code. However, that being said, it can be a valuable contribution to take an existing, but not fully maintained, library you are interested in and give it a new lease of life.

NOTE: All libraries in Boost are tested when the super-project is tested, so even without a dedicated maintainer the libraries must pass a series of automated tests.

== Contribute a New Library

This is the big dog of contributions. There are developers who have contributed several libraries to Boost. Start by reading the xref:requirements/library-requirements.adoc[] section, and make sure to engage the Boost community _before_ getting too deep into a massive coding project.

== See Also

* xref:contributor-community-introduction.adoc[]
* xref:formal-reviews:ROOT:index.adoc[]
* xref:user-guide:ROOT:user-community-introduction.adoc[]