268 lines
13 KiB
Plaintext
268 lines
13 KiB
Plaintext
= Spring AI Contributor Guidelines
|
||
|
||
Do you have something you'd like to contribute to **Spring AI**?
|
||
We welcome pull requests, but ask that you carefully read this document first to understand how best to submit them;
|
||
what kind of changes are likely to be accepted; and what to expect from the Spring team when evaluating your submission.
|
||
|
||
Please refer back to this document as a checklist before issuing any pull request; this will save time for everyone!
|
||
|
||
== Code of Conduct
|
||
This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of conduct].
|
||
By participating, you are expected to uphold this code. Please report unacceptable behavior to
|
||
spring-code-of-conduct@pivotal.io.
|
||
|
||
== Understand the basics
|
||
|
||
Not sure what a *pull request* is, or how to submit one? Take a look at GitHub's excellent documentation:
|
||
https://help.github.com/articles/using-pull-requests/[Using Pull Requests] first.
|
||
|
||
== Search GitHub ticket first; create an issue if necessary
|
||
|
||
Is there already an issue that addresses your concern? Search the
|
||
https://github.com/spring-projects/spring-ai/issues[GitHub issue tracker] to see if you can find something similar.
|
||
If not, please create a new issue before submitting a pull request unless the change is truly trivial, e.g. typo fixes,
|
||
removing compiler warnings, etc.
|
||
|
||
== Developer Certificate of Origin
|
||
|
||
All commits must include a __Signed-off-by__ trailer at the end of each commit message to indicate that the contributor agrees to the Developer Certificate of Origin.
|
||
For additional details, please refer to the blog post https://spring.io/blog/2025/01/06/hello-dco-goodbye-cla-simplifying-contributions-to-spring[Hello DCO, Goodbye CLA: Simplifying Contributions to Spring].
|
||
|
||
== Fork the Repository
|
||
|
||
1. Go to https://github.com/spring-projects/spring-ai[https://github.com/spring-projects/spring-ai]
|
||
2. Hit the "fork" button and choose your own GitHub account as the target
|
||
3. For more detail see https://help.github.com/fork-a-repo/[Fork A Repo].
|
||
|
||
== Setup your Local Development Environment
|
||
|
||
1. `git clone --recursive git@github.com:<your-github-username>/spring-ai.git`
|
||
2. `cd spring-ai`
|
||
3. `git remote show`
|
||
_you should see only 'origin' - which is the fork you created for your own GitHub account_
|
||
4. `git remote add upstream git@github.com:spring-projects/spring-ai.git`
|
||
5. `git remote show`
|
||
_you should now see 'upstream' in addition to 'origin' where 'upstream' is the SpringIO repository from which releases are built_
|
||
6. `git fetch --all`
|
||
7. `git branch -a`
|
||
_you should see branches on origin as well as upstream, including 'main'_
|
||
|
||
== A Day in the Life of a Contributor
|
||
|
||
* _Always_ work on topic branches (Typically use the GitHub issue ID as the branch name).
|
||
- For example, to create and switch to a new branch for issue GH-123: `git checkout -b GH-123`
|
||
* You might be working on several different topic branches at any given time, but when at a stopping point for one of those branches, commit (a local operation).
|
||
* Please follow the "Commit Guidelines" described in
|
||
https://git-scm.com/book/ms/v2/Distributed-Git-Contributing-to-a-Project[this chapter of Pro Git].
|
||
* Then to begin working on another issue (say GH-101): `git checkout GH-101`. The _-b_ flag is not needed if that
|
||
branch already exists in your local repository.
|
||
* When ready to resolve an issue or to collaborate with others, you can push your branch to origin (your fork),
|
||
e.g.: `git push origin GH-123`
|
||
* If you want to collaborate with another contributor, have them fork your repository (add it as a remote) and
|
||
`git fetch <your-username>` to grab your branch.
|
||
Alternatively, they can use `git fetch --all` to sync their local state with all of their remotes.
|
||
* If you grant that collaborator push access to your repository, they can even apply their changes to your branch.
|
||
* When ready for your contribution to be reviewed for potential inclusion in the main branch of the canonical
|
||
spring-ai repository (what you know as 'upstream'), issue a pull request to the SpringSource repository
|
||
(for more detail, see https://help.github.com/articles/using-pull-requests/[Using pull requests]).
|
||
* The project lead may merge your changes into the upstream main branch as-is, he may keep the pull request open yet
|
||
add a comment about something that should be modified, or he might reject the pull request by closing it.
|
||
* A prerequisite for any pull request is that it will be cleanly merge-able with the upstream main's current state.
|
||
**This is the responsibility of any contributor.**
|
||
If your pull request cannot be applied cleanly, the project lead will most likely add a comment requesting that you make
|
||
it merge-able.
|
||
For a full explanation, see https://git-scm.com/book/en/Git-Branching-Rebasing[the Pro Git section on rebasing].
|
||
As stated there: _"> Often, you’ll do this to make sure your commits apply cleanly on a remote branch — perhaps in a
|
||
project to which you’re trying to contribute but that you don’t maintain."_
|
||
|
||
== Keeping your Local Code in Sync
|
||
* As mentioned above, you should always work on topic branches (since 'main' is a moving target). However, you do want
|
||
to always keep your own 'origin' main branch in synch with the 'upstream' main.
|
||
* Within your local working directory, you can sync up all remotes' branches with: `git fetch --all`
|
||
* While on your own local main branch: `git pull upstream main` (which is the equivalent of fetching upstream/main
|
||
and merging that into the branch you are in currently)
|
||
* Now that you're in synch, switch to the topic branch where you plan to work, e.g.: `git checkout -b GH-123`
|
||
* When you get to a stopping point: `git commit`
|
||
* If changes have occurred on the upstream/main while you were working you can synch again:
|
||
- Switch back to main: `git checkout main`
|
||
- Then: `git pull upstream main`
|
||
- Switch back to the topic branch: `git checkout GH-123` (no -b needed since the branch already exists)
|
||
- Rebase the topic branch to minimize the distance between it and your recently synched main branch: `git rebase main`
|
||
(Again, for more detail see https://git-scm.com/book/en/Git-Branching-Rebasing[the Pro Git section on rebasing]).
|
||
* **Note** You cannot rebase if you have already pushed your branch to your remote because you'd be rewriting history
|
||
(see **'The Perils of Rebasing'** in the article).
|
||
If you rebase by mistake, you can undo it as discussed
|
||
https://stackoverflow.com/questions/134882/undoing-a-git-rebase[in this StackOverflow discussion].
|
||
Once you have published your branch, you need to merge in the main rather than rebasing.
|
||
* Now, if you issue a pull request, it is much more likely to be merged without conflicts.
|
||
Most likely, any pull request that would produce conflicts will be deferred until the issuer of that pull request makes
|
||
these adjustments.
|
||
* Assuming your pull request is merged into the 'upstream' main, you will actually end up pulling that change into
|
||
your own main eventually, and at that time, you may decide to delete the topic branch from your local repository and
|
||
your fork (origin) if you pushed it there.
|
||
- to delete the local branch: `git branch -d GH-123`
|
||
- to delete the branch from your origin: `git push origin :GH-123`
|
||
|
||
== Maintain a linear commit history
|
||
|
||
When merging to main, the project __always__ uses fast-forward merges.
|
||
When issuing pull requests, please ensure that your commit history is linear.
|
||
From the command line you can check this using:
|
||
|
||
----
|
||
log --graph --pretty=oneline
|
||
----
|
||
|
||
As this may cause lots of typing, we recommend creating a global alias, e.g. `git logg` for this:
|
||
|
||
----
|
||
git config --global alias.logg 'log --graph --pretty=oneline'
|
||
----
|
||
|
||
This command, will provide the following output, which in this case shows a nice linear history:
|
||
|
||
----
|
||
* c129a02e6c752b49bacd4a445092a44f66c2a1e9 INT-2721 Increase Timers on JDBC Delayer Tests
|
||
* 14e556ce23d49229c420632cef608630b1d82e7d INT-2620 Fix Debug Log
|
||
* 6140aa7b2cfb6ae309c55a157e94b44e5d0bea4f INT-3037 Fix JDBC MS Discard After Completion
|
||
* 077f2b24ea871a3937c513e08241d1c6cb9c9179 Update Spring Social Twitter to 1.0.5
|
||
* 6d4f2b46d859c903881a561c35aa28df68f8faf3 INT-3053 Allow task-executor on <reply-listener/>
|
||
* 56f9581b85a8a40bbcf2461ffc0753212669a68d Update Spring Social Twitter version to 1.0.4
|
||
----
|
||
|
||
If you see intersecting lines, that usually means that you forgot to rebase you branch.
|
||
As mentioned earlier, **please rebase against main** before issuing a pull request.
|
||
|
||
== Mind the whitespace
|
||
|
||
Please carefully follow the whitespace and formatting conventions already present in the framework.
|
||
|
||
1. Tabs, not spaces
|
||
2. Unix (LF), not DOS (CRLF) line endings
|
||
3. Eliminate all trailing whitespace
|
||
4. Wrap Javadoc at 90 characters
|
||
5. Aim to wrap code at 120 characters, but favor readability over wrapping
|
||
6. Preserve existing formatting; i.e. do not reformat code for its own sake
|
||
7. Search the codebase using `git grep` and other tools to discover common
|
||
naming conventions, etc.
|
||
8. Latin-1 (ISO-8859-1) encoding for Java sources; use `native2ascii` to convert
|
||
if necessary
|
||
|
||
== Add Apache license header to all new classes
|
||
|
||
[source, java]
|
||
----
|
||
/*
|
||
* Copyright 2016 the original author or authors.
|
||
*
|
||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||
* you may not use this file except in compliance with the License.
|
||
* You may obtain a copy of the License at
|
||
*
|
||
* https://www.apache.org/licenses/LICENSE-2.0
|
||
*
|
||
* Unless required by applicable law or agreed to in writing, software
|
||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
* See the License for the specific language governing permissions and
|
||
* limitations under the License.
|
||
*/
|
||
|
||
package ...;
|
||
----
|
||
|
||
== Update license header to modified files as necessary
|
||
|
||
Always check the date range in the Apache license header. For example, if you've modified a file in 2016 whose header
|
||
still reads
|
||
|
||
[source java]
|
||
----
|
||
* Copyright 2002-2011 the original author or authors.
|
||
----
|
||
|
||
then be sure to update it to 2016 appropriately
|
||
|
||
[source java]
|
||
----
|
||
* Copyright 2002-2016 the original author or authors.
|
||
----
|
||
|
||
== Use @since tags
|
||
|
||
Use @since tags for newly-added public API types and methods e.g.
|
||
|
||
[source java]
|
||
----
|
||
/**
|
||
* ...
|
||
*
|
||
* @author First Last
|
||
* @since 3.0
|
||
* @see ...
|
||
*/
|
||
----
|
||
|
||
== Submit JUnit test cases for all behavior changes
|
||
|
||
Search the codebase to find related unit tests and add additional @Test methods within. It is also acceptable to submit test cases on a per GitHub issue basis.
|
||
|
||
== Squash commits
|
||
|
||
Use `git rebase --interactive`, `git add --patch` and other tools to "squash" multiple commits into atomic changes.
|
||
In addition to the man pages for git, there are many resources online to help you understand how these tools work.
|
||
|
||
== Use your real name in git commits
|
||
|
||
Please configure git to use your real first and last name for any commits you intend to submit as pull requests. For example, this is not acceptable:
|
||
|
||
Author: Nickname <user@mail.com>
|
||
|
||
Rather, please include your first and last name, properly capitalized, as submitted against the SpringSource contributor license agreement:
|
||
|
||
Author: First Last <user@mail.com>
|
||
|
||
This helps ensure traceability against the CLA, and also goes a long way to ensuring useful output from tools like `git shortlog` and others.
|
||
|
||
You can configure this globally via the account admin area GitHub (useful for fork-and-edit cases); globally with
|
||
|
||
git config --global user.name "First Last"
|
||
git config --global user.email user@mail.com
|
||
|
||
or locally for the *spring-ai* repository only by omitting the '--global' flag:
|
||
|
||
cd spring-ai
|
||
git config user.name "First Last"
|
||
git config user.email user@mail.com
|
||
|
||
== Run all tests prior to submission
|
||
|
||
Make sure that all tests pass prior to submitting your pull request.
|
||
|
||
== Mention your pull request on the associated GitHub issue
|
||
|
||
Add a comment to the associated GitHub issue(s) linking to your new pull request.
|
||
|
||
== Provide a Link to the GitHub issue in the Associated Pull Request
|
||
|
||
There are multiple ways to link a Pull Request to a GitHub issue as described
|
||
https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue[here].
|
||
|
||
One way would be to add a GitHub issue link to your first commit comment of the pull request on the second line,
|
||
so your commit message may look like this:
|
||
|
||
----
|
||
GH-1: Add Contribution Guidelines
|
||
|
||
Fixes GH-1 (https://github.com/spring-projects/spring-ai/issues/1)
|
||
|
||
* add `CONTRIBUTING.adoc` describing the Contribution procedure
|
||
* mention Contribution Guidelines in the `README.md`
|
||
* mention CODE_OF_CONDUCT in the `README.md`
|
||
----
|
||
|
||
Also by using specific
|
||
https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword[keywords]
|
||
you can link to a GitHub issue like so:
|
||
|
||
Closes #10 |