👍🎉✨ Thank you for investing your time in contributing to the 3W Project! ✨🎉👍
We expect to receive various types of contributions from individuals, research institutions, startups, companies and partner oil operators.
In this guide we present how you can propose each type of contributions that we expect.
The recommended first step is to read this README for an overview of the 3W Project.
Please do not open an issue to ask questions. Click on the Discussions link that appears in the top menu. If you don't get clarification, please open discussions to ask your questions so we can answer them.
Before you can contribute to this project, you need to read and agree to the following documents:
- CODE OF CONDUCT;
- CONTRIBUTOR LICENSE AGREEMENT;
- This contributing guide.
It is also very important to know, participate and follow the discussions. Click on the Discussions link that appears in the top menu.
We expect to receive contributions at different levels, as shown in the figure below. Objects with background in yellow indicate types of contributions enabled by the 3W Project current version. The other objects above the 3W Project indicate types of contributions that will be enabled in the next versions. Some examples of contributions at each level are:
- Level 1:
- You can identify and report issues with data or annotations;
- You can propose adding real, simulated or hand-drawn instances.
- Level 2:
- You can identify, report and fix bugs;
- You can propose documentation improvements;
- You can recommend new specific problems.
- Level 3:
- You can develop and propose approaches and algorithms for already incorporated problems;
- You can elaborate and send us new overvies;
- You can idealize, develop and propose new useful tools.
- Level 4:
- You can develop and submit us ensemble methods;
- You can generate and propose more complex and complete tools.
- Level n:
- We see no limit to the levels for contributions.
At level 1, the 3W Dataset consists of multiple Parquet files saved in subdirectories of the dataset directory and structured as detailed here.
At level 2, the 3W Toolkit is implemented in sub-modules as discribed here.
To execute examples of how to use the 3W Toolkit available in this repository, see the instructions related to reproducibility.
We seek to adopt trunk-based development. This article explains some of the justifications and benefits of this practice.
For each type of expected contribution, there is a subsection below with specific instructions. The last subsection specifies additional requirements for contributions to be incorporated into this project.
As far as we know, the 3W Dataset was useful and cited by the works listed here. If you know any other paper, master's degree dissertation or doctoral thesis that cites the 3W Dataset, we will be grateful if you let us know by commenting this discussion. If you use any resource published in this repository, we ask that it be properly cited in your work. Click on the Cite this repository link on this repository landing page to access different citation formats supported by the GitHub citation feature.
Please open an issue to report any bug. If you've implemented a fix, please create a pull request on a branch called bugs.
We believe that any part of the documentation for this project can be improved, including this guide. You can work on that and then create a pull requests on a branch called documentation_improvements directly.
It is important to keep in mind that this toolkit's documentation is generated in english and in Google format with autoDocstring - Python Docstring Generator, which follows PEP 257, and pdoc3.
Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability of the 3W Project are also welcome. In this case, please create a pull requests on a branch called cosmetic_improvements directly.
If you intend to work and propose a more significant improvement, please consult our backlog first. If you have any questions about the most aligned strategy for the 3W Project, please consult or create discussions. When your improvement is ready, please create a pull request on a branch called other_improvements.
It is important to keep in mind that all source code is implemented according to the style guide established by PEP 8. This is guaranteed with the use of the Black formatter with default options. Therefore, while codes have lines up to 88 characters (Black formatter's default option), each line with docstring or comment must be up to 72 characters long as established in PEP 8.
Visualization is one of the most important steps in this type of project. Therefore, you can propose Jupyter Notebooks with different views. For this, submit a pull request on a branch called new_3w_datasets_overviews with a file named overviews\[your_name_here]\main.ipynb that you've developed. If we like your overview, your file could be listed in this repository as a 3W Toolkit's example of use.
Would you like to share in this repository as 3W Toolkit's examples of use approaches and algorithms for already incorporated problems? The procedure for this is to submit a pull request on a branch called new_approaches_and_algorithms with Jupyter Notebooks that you've developed in the directory corresponding to the chosen problem.
Specific problems will be incorporated into this project gradually. At this point, we can work on:
Here are additional requirements for contributions to be incorporated into this project:
- As the forking workflow is used, every PR needs to be generated in a fork. A tutorial about different Git Workflows is available here;
- PRs will only be accepted if they pass the check automatically performed by the GitHub Action specified in action-black.yml. If this check fails, check the generated log, use the latest version of Black formatter to locally format the files as needed, then generate another PR.
The list of priority improvements for the 3W Project that we intend to develop collaboratively with the community is detailed in the file BACKLOG.md.