You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Thank you for your interest in contributing to DataJoint Elements!
3
+
Thank you for your interest in contributing to DataJoint open-source software!
4
4
5
-
These guidelines are designed to ensure smooth collaboration, high-quality
6
-
contributions, and a welcoming environment for all contributors. Please take a moment to
7
-
review this document in order to make the contribution process easy and effective for
8
-
everyone involved.
5
+
These guidelines are designed to ensure smooth collaboration, high-quality contributions, and a welcoming environment for all contributors. Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.
9
6
10
-
The principal maintainer of DataJoint and associated tools is the DataJoint company. The
11
-
pronouns “we” and “us” in this guideline refer to the principal maintainers. We invite
12
-
reviews and contributions of the open-source software. We compiled these guidelines to
13
-
make this work clear and efficient.
7
+
The principal maintainer of DataJoint and associated tools is the DataJoint company. The pronouns “we” and “us” in this guideline refer to the principal maintainers. We invite reviews and contributions of the open-source software. We compiled these guidelines to make this work clear and efficient.
8
+
9
+
## Table of Contents
10
+
-[Community Engagement](#community-engagement)
11
+
-[How to Contribute](#how-to-contribute)
12
+
-[Project Lists](#project-lists)
13
+
-[Prerequisites](#prerequisites)
14
+
-[Reporting Bugs](#reporting-bugs)
15
+
-[Proposing Features or Enhancements](#proposing-features-or-enhancements)
For general questions, ideas, discussions or live debugging sessions, please join [DataJoint Slack](https://join.slack.com/t/datajoint/shared_invite/enQtMjkwNjQxMjI5MDk0LTQ3ZjFiZmNmNGVkYWFkYjgwYjdhNTBlZTBmMWEyZDc2NzZlYTBjOTNmYzYwOWRmOGFmN2MyYzU0OWQ0MWZiYTE) or [Stack Overflow](https://stackoverflow.com/questions/tagged/datajoint), but for direct technical issues should stay in `Github Issue` in the respective project's repository. Response times may vary depending on maintainer availability.
25
+
26
+
- For resolving bugs, errors, or general debugging help, please submit it through `Github Issue` in the respective repository.
27
+
- For live debugging, urgent help, or broader discussions, join the [DataJoint Slack](https://join.slack.com/t/datajoint/shared_invite/enQtMjkwNjQxMjI5MDk0LTQ3ZjFiZmNmNGVkYWFkYjgwYjdhNTBlZTBmMWEyZDc2NzZlYTBjOTNmYzYwOWRmOGFmN2MyYzU0OWQ0MWZiYTE).
28
+
- For feature requests, please open an issue directly in the `Github Issue` of the respective repository providing sufficient details to facilitate discussion and prioritization.
- Most of [Docker images](https://github.com/orgs/datajoint/repositories?q=docker) expect the ones listed above
56
+
57
+
### Prerequisites
58
+
59
+
- Familiarize yourself with the project documentation and guidelines.
60
+
- Start with reading the repository's `README.md` and `CONTRIBUTION.md`. You should expect to find the following instructions for the respective project:
61
+
- Installation instructions.
62
+
- Development environment setup.
63
+
- Testing instructions.
22
64
23
-
For general questions or ideas, discussions and live debugging support, please join
or [other community forums](https://stackoverflow.com/questions/tagged/datajoint), but
26
-
direct technical contributions should stay in GitHub. Response times may vary depending
27
-
on maintainer availability.
65
+
> Please open an issue in the respective repository if any of those instructions in the documentations or `READMD.md` are unclear to you. Contributions to documentations are equivalently important to any code for the community, please help us to resolve any confusions in documentations.
28
66
29
-
### Reporting Issues
67
+
### Reporting Bugs
30
68
31
-
Use `GitHub Issues` to report bugs or request features. Clearly describe the issue,
32
-
including:
69
+
Before you open up a new issue, please check `Github Issue` to see if there are any related open/closed issues or open/closed PRs to avoid duplicates. If not, please open a new issue with clearly description of your bug, including:
33
70
34
71
- Steps to reproduce (if applicable).
35
72
- Expected and actual outcomes.
36
73
- Any relevant error messages, logs, or screenshots.
37
-
- Include environment details (e.g., OS, library versions) to speed up troubleshooting.
74
+
- Include environment details (e.g., OS, pip, conda dependencies) to speed up troubleshooting.
38
75
39
-
Check existing issues to avoid duplicates.
76
+
### Proposing Features or Enhancements
40
77
41
-
### Proposing Features/Changes
42
-
43
-
Before significant contributions, open a `GitHub Issue` to discuss your proposal. Please
44
-
include:
78
+
Before starting your significant work, open a `Github Issue` to discuss your proposal first. Please include:
45
79
46
80
- A clear problem statement.
47
81
- Proposed solution or feature details.
48
82
- Relevant examples or use cases.
49
83
50
-
### Submitting Pull Requests (PRs)
51
-
52
-
1. Fork the repository and clone it to your local machine.
53
-
2. Create a descriptive branch name, e.g., `fix/typo-docs` or `feature/add-logging`.
54
-
3. Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): Use
55
-
commit messages following the commit types for versioning:
84
+
> There will be a repository for DataJoint Enhancement Proposal to centralize all proposals, it is currently in progress.
56
85
57
-
-`fix`: Bug fixes (PATCH in Semantic Versioning).
58
-
-`feat`: New features (MINOR in Semantic Versioning).
59
-
-`docs`: Documentation updates.
60
-
-`Breaking changes`: Use ! after the type or add BREAKING CHANGE in the commit footer.
> In DataJoint, we use **[Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow)** to manage contributions to keep the main fork's branch management clean.
89
+
90
+
1. Fork the repository to your own Github account and clone it to your local machine.
91
+
- Please remember to always sync your fork's main branch with the DataJoint repository's main branch before starting your work.
92
+
- In your own fork, we suggest you use [Feature Branch Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow) to manage your branches in your own fork, just in case someone will work on multiple contributions at the same time.
93
+
2. Create a descriptive feature/fix branch from your fork's main branch, e.g., `fix/typo-docs` or `feature/add-logging`.
94
+
3. Optionally, but highly recommended to follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to make commit messages easier to be searched and categorized: If you use VSCode, please install [Conventional Commits](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits) extention, it will help you to edit your commit messages following the commit types for versioning:
95
+
-`fix`: Bug fixes.
96
+
-`feat`: New features.
97
+
-`docs`: Documentation updates.
98
+
-`Breaking changes`: Changes would break backward compatibility, may affect the existing users when they upgrade. Use ! after the type or add BREAKING CHANGE in the commit footer.
99
+
-`chore`: Like the name, it is a chore.
100
+
- Example, if you are not using the VSCode extension: `git commit -m "fix(auth): resolve token expiration bug."`
64
101
4. Reference related issue(s) in your PR description (e.g., Closes #123).
65
-
5. Cover new functionality or bug fixes with appropriate tests. Ensure all tests pass
66
-
before submission. Typically as it relates to tests, this means:
102
+
5. Cover new functionality or bug fixes with appropriate tests. Ensure all tests pass before submission. Typically as it relates to tests, this means:
67
103
1. No syntax errors
68
104
2. No integration errors
69
105
3. No style errors e.g. PEP8, etc.
70
106
4. Similar or better code coverage
71
-
6. Additional documentation to reflect new feature or behavior introduced.
107
+
6.**Additional documentation** to reflect new feature or behavior introduced.
72
108
7. Provide a detailed PR description explaining the changes and their impact.
73
-
8. Submit the PR for review. Maintainers will also ensure that PR’s have the appropriate
74
-
assignment for reviewer.
109
+
8. Submit the PR for review. Maintainers will also ensure that PR’s have the appropriate assignment for reviewer.
110
+
111
+
### Code Reviews
75
112
76
113
A contributor should not approve or merge their own PR. A maintainer will review and
77
114
approve the PR.
@@ -81,52 +118,47 @@ contributor’s fork. A less intrusive way to collaborate would be for the revie
81
118
to the contributor’s fork/branch that is associated with the main PR currently in
82
119
review.
83
120
84
-
### Code Reviews
121
+
Expect constructive feedback from maintainers. Maintainers will review your PR and suggest changes or improvements. Be responsive to feedback and iterate as needed. Reviews focus on code quality and adherence to standards, and documentation and test coverage. Once approved, the PR will be merged.
85
122
86
-
Expect constructive feedback from maintainers. Maintainers will review your PR and
87
-
suggest changes or improvements. Be responsive to feedback and iterate as needed.
88
-
Reviews focus on code quality and adherence to standards, and documentation and test
-`MAJOR` version when you make incompatible API changes,
132
+
-`MAJOR` version bump when breaking changes make backward incompatible.
99
133
100
-
-`MINOR` version when you add functionality in a backwards compatible manner, and
134
+
-`MINOR` version bump when added functionalities is backward compatible.
101
135
102
-
-`PATCH` version when you make backwards compatible bug fixes.
136
+
-`PATCH/MICRO` version when included bug fixes are backward compatible.
103
137
104
-
Each release requires tagging the commit appropriately and is then issued following the
105
-
GitHub automated semantic release. The release and Changelog will be generated
106
-
automatically after the PR is merged.
138
+
> Backward Compatible means that the existing users can upgrade to the new version without any changes to their existing code.
107
139
108
-
## Community Engagement
140
+
For DataJoint open-source projects, we have two ways of making a release at this moment since we are improving the release process, and we will eventually consolidate into one way:
109
141
110
-
- For resolving bugs, errors, or debugging issues, please submit it through **GitHub
111
-
Issues**.
112
-
- For live debugging, urgent help, or broader discussions, join the
Keep in mind maintainers’ availability may be limited.
115
-
- For feature requests, directly in the GitHub Issue Tracker of the respective
116
-
repository Provide sufficient details to facilitate discussion and prioritization.
142
+
- Datajoint Python release, the future direction:
143
+
- We use `Github Label` and [PR Labeler action](https://github.com/actions/labeler) to categorize each PR.
144
+
- Then we use [Release Drafter](https://github.com/release-drafter/release-drafter) to manually trigger a Github Actions workflow to make a draft release.
145
+
- Changelog will be provided by [Github Compare URL](https://github.com/datajoint/datajoint-python/compare/v0.14.2...v0.14.3) at the end of the release note.
146
+
- Then we manually publish the draft release to trigger a release Github Actions workflow.
147
+
- Others:
148
+
- This process is very dependent on conventional commits and tagging.
149
+
- It will be triggered by pushing a new tag to the repository.
150
+
- It uses [python-semantic-release](https://python-semantic-release.readthedocs.io/en/latest/) to parse all the conventional commits for the release note and `CHANGELOG.md`.
117
151
118
-
## Prerequisites
152
+
> We found the former resolver would work the best for our community since contributors are from different background, we do not want to require them to adopt conventional commits.
119
153
120
-
- Familiarize yourself with the project documentation and guidelines.
121
-
- Install necessary tools and dependencies listed in the repository's `README`.
154
+
[Back to Top](#table-of-contents)
122
155
123
156
## Contribution Acknowledgment
124
157
125
-
We deeply appreciate every contribution! By adhering to these guidelines, you help
126
-
maintain the quality, usability, and success of DataJoint Elements.
158
+
We deeply appreciate every contribution! By adhering to these guidelines, you help maintain the quality, usability, and success of any DataJoint open-source software.
127
159
128
-
For any questions, feel free to reach out via GitHub Issues, our
For any questions, feel free to reach out via `Github Issue` in the specific repository, our [Community Slack](https://join.slack.com/t/datajoint/shared_invite/enQtMjkwNjQxMjI5MDk0LTQ3ZjFiZmNmNGVkYWFkYjgwYjdhNTBlZTBmMWEyZDc2NzZlYTBjOTNmYzYwOWRmOGFmN2MyYzU0OWQ0MWZiYTE) or contact `[email protected]`.
0 commit comments