Project contribution guidelines.
First off, thanks for your interest! While this guide focuses on technical development, if you are looking to contribute to the project but are non-technical, you can still contribute! For example, you can contribute by filing issues, writing feature requests, updating documentation, providing build and infrastructure support, and helping market and promote the project, among other things. Every bit helps, and we are grateful for your time and effort!
Before contributing, read the [Code of Conduct][jupyter-code-of-conduct], which details the bare minimum behavior expectations that the project requires of its contributors.
When filing new issues and commenting on existing issues on this repository, please ensure that discussions are related to concrete technical issues.
Before filing a potential bug report,
- Search for existing issues and pull requests.
- Try some debugging techniques to help isolate the problem, including logging inputs and outputs.
If the source of the problem is a third party package, file a bug report with the relevant package author, rather than on this repository.
When filing an issue, provide the following, where possible:
- A description of the issue.
- Links to any related issues.
- The full error message, including the stacktrace.
- The sequence of steps required to reproduce the issue.
- A minimal working example; i.e., the smallest chunk of code that triggers the error. If the code is larger than
50
lines, consider creating a gist. - The expected results.
- List of affected environments; e.g., browser, browser version,
npm
version, Node.js version, operating system, and the project version.
When pasting code blocks or output, use triple backticks to enable proper formatting. Surround inline code with single backticks. For other Markdown formatting tips and trips, see GitHub's Markdown guide.
Be aware that the @
symbol tags users on GitHub, so always surround package names with backticks (e.g., @jupyterlab/dataregistry-extension
).
By contributing code to the project, you are agreeing to release it under the project license.
Before contributing code, be sure to
- read and understand the licensing terms.
For instructions on how to setup and configure your environment, be sure to
- read and follow the development guide.
If you want to contribute a new feature or a breaking change to this project, be sure to
- file an issue detailing the proposed change.
- wait for feature request approval.
- adhere to the guidance set forth in the feature request comments.
If you are unfamiliar with Git, the version control system used by GitHub and this project,
Next, take a look around the project, noting the style and organization of documentation, tests, examples, and source implementations. Consistency is highly prioritized within this project. Thus, the more you are able to match and adhere to project conventions and style, the more likely your contribution will be accepted. While we have done our best to automate linting and style guidelines, such automation is not perfect and cannot adequately capture the inevitable exceptions and nuance to many rules. In short, the more you study existing practice, the better prepared you will be to contribute to this project.
Create a GitHub account. The project uses GitHub exclusively for hosting source code, managing issues and pull requests, triggering continuous integration, and reporting.
Fork the repository on GitHub and clone the repository to your local machine.
$ git clone https://github.com/<username>/juptyerlab-data-explorer.git
where <username>
is your GitHub username. The repository may have a large commit history, leading to slow download times. If you are not interested in code archeology, you can reduce the download time by limiting the clone depth.
$ git clone --depth=<depth> https://github.com/<username>/juptyerlab-data-explorer.git
where <depth>
refers to the number of commits you want to download (as few as 1
and as many as the entire project history).
If you are behind a firewall, you may need to use the https
protocol, rather than the git
protocol.
$ git config --global url."https://".insteadOf git://
Once you have finished cloning the repository into the destination directory, you should see the folder jupyterlab-data-explorer
. To proceed with configuring your environment, navigate to the project folder.
$ cd jupyterlab-data-explorer
And finally, add an upstream
remote to allow syncing changes between this repository and your local version.
$ git remote add upstream git://github.com/jupyterlab/jupyterlab-data-explorer.git
For modifications intended to be included in this repository, create a new local branch.
$ git checkout -b <branch>
where <branch>
is the branch name. The master
branch for this repository is protected, and direct modifications to this branch will not be accepted. Instead, all contributions should be made on non-master local branches, including documentation changes and other non-code modifications.
Start making your changes and/or implementing the new feature.
Ensure that you have configured Git to know your name and email address.
$ git config --global user.name "Jane Doe"
$ git config --global user.email "[email protected]"
Add changed files and commit.
$ git add files/which/changed
$ git commit
To incorporate recent changes from the upstream
repository during development, you should rebase your local branch, reapplying your local commits on top of the current upstream HEAD
. This procedure is in contrast to performing a standard merge, which may interleave development histories. The rationale is twofold:
- interleaved histories make squashing commits more difficult
- a standard merge increases the risk of incomplete/broken commits appearing in the Git history.
An ideal commit history is one in which, at no point in time, is the project in a broken state. While not always possible (mistakes happen), striving for this ideal facilitates time travel and software archeology.
$ git fetch upstream
$ git rebase upstream/develop
Tests should accompany all bug fixes and features. For guidance on how to write tests, consult existing tests within the project.
Before submitting a pull request to the upstream
repository, ensure that all tests pass, including linting.
Any pull requests which include failing tests and/or lint errors will not be accepted.
To setup dev environment and run JupyterLab:
$ jlpm run build
$ jupyter lab build
$ jupyter lab
To make changes and have JupyterLab rebuild withour restarting:
$ jlpm run build:watch
$ jupyter lab --watch
To run tests:
$ jlpm run test
When debugging failing tests, to run UI tests in a non-headless browser window:
$ jlpm run test:debug
During UI testing, when a test fails, a screenshot is taken of the current browser state and saved in a local screenshots
folder to assist in debugging.
If tests fail during continuous integration, a folder containing screenshots can be downloaded as an archive from the Actions panel on GitHub.
Push your changes to your remote GitHub repository.
$ git push origin <branch>
where <branch>
is the name of your branch.
Once your contribution is ready to be incorporated in the upstream
repository, open a pull request against the master
branch. A project contributor will review the contribution, provide feedback, and potentially request changes.
Receiving feedback is the most important, and often the most valuable, part of the submission process. Don't get disheartened!
To make changes to your pull request, make changes to your branch. Each time you push changes to your forked repository, GitHub will automatically update the pull request.
$ git add files/which/changed
$ git commit
$ git push origin <branch>
Note that, once a pull request has been made (i.e., your local repository commits have been pushed to a remote server), you should not perform any further rewriting of Git history. If the history needs modification, a contributor will modify the history during the merge process. The rationale for not rewriting public history is that doing so invalidates the commit history for anyone else who has pulled your changes, thus imposing additional burdens on collaborators to ensure that their local versions match the modified history.
After any changes have been resolved, a contributor will approve a pull request for inclusion in the project. Once merged, the pull request will be updated with the merge commit, and the pull request will be closed.
Note that, during the merge process, multiple commits will often be squashed.
Congratulations! You are an official contributor to this project! Thank you for your hard work and patience!
- When linking to specific lines of code in an issue or a pull request, hit the
y
key while viewing a file on GitHub. Doing so reloads the page with a URL that includes the specific version of the file you are viewing. This ensures that, when you refer to specific lines, these same lines can be easily viewed in the future, even if the content of the file changes. - GitHub does not send notifications when you push a commit and update a pull request, so be sure to comment on the pull request thread to inform reviewers that you have made changes.
By contributing tests to the project, you are agreeing to release them under the project license.
By contributing documentation to the project, you are agreeing to release it under the project license.
Project documentation is localized within each package. Similar to code, you should modify documentation using Git.
By making a contribution to this project, I certify that:
- (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
- (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
- (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
- (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
Phew. While the above may be a lot to remember, even for what seem like minor changes, eventually it becomes routine and part of the normal development flow. Part of the motivation for enforcing process is to ensure that all code contributions meet a certain quality threshold, thus helping reviewers focus less on non-substantive issues like style and failing tests and more on substantive issues such as contribution content and merit. Know that your patience, hard work, time, and effort are greatly appreciated!