Contributing to the LDS Java Stack project
Note: This page only applies to ICS employees. There is currently no publicly-accessible repository of source code for the LDS Java Stack, and no current plans to make one available. So, the workflow described below cannot be made to work for LDSTech community volunteers; our apologies.
There are generally two cases:
- 1. You've already cloned a repository where you do not have "push" rights, and you've made changes and committed them to your local clone.
- 2. You haven't started making changes yet.
In both cases, the general idea is to get your changes pushed to a repository that you control in Stash, and then to make the upstream project's owners aware of your changes by preparing a "Pull Request".
- 1 Get your changes pushed to a repository that you control in Stash
- 2 Inform the upstream project of your changes by creating a "Pull Request"
Get your changes pushed to a repository that you control in Stash
If you've already got changes committed to your local clone of a Stack module repository you can't push to
In this case, you have already found the relevant repository, and you've created a clone of it. You've made some changes, and committed them to your local clone repository. The only problem that you can't push your changes from your local repository back up to the original repo, because you don't have rights on that repo. At this point, you must create a "fork" repository that you can push to, and then reconfigure your existing local clone (where you've already done the work and committed) to push to your fork.
- 1. Use Stash to create a fork of that original repository
- All Stack modules should be "Public" (readable by everyone in ICS) as well as have "forking" enabled on the repository. To create a fork, use your browser to navigate to to the project's page in Stash, and click the "Fork" button near the top left of the page. The form that appears when you click that button prompts you to choose a project within which to group this fork. It is recommended that you create the fork under your "personal" project, which is the default.
- 2. Make your local workspace point at your fork, instead of the original
- 3. Push your changes up to your fork
If you haven't already committed changes to a repository you're not allowed to push
- 1. Locate the appropriate repository in Stash
- If an issue exists in JIRA for the changes you are proposing, it is likely that the JIRA issue identifies the relevant Stack module (in the issue's "component" field).
- Here are the locations of some modules' repositories in Stash:
- 2. Fork that module's Stash repository
- Forking a repository means creating a server-side clone of a repository. This clone is a new repository owned by you, preserving the entire contents and commit history of the original, and, unlike the original, to which you can push commits. Further, Stash provides a method, called "Pull Requests" by which you can inform the upstream repository's owner of changes you've made. They then can review your changes and merge those into their repository. In many cases, this merging can be done completely automatically. This is a great benefit both to the project owners and the folks who depend upon those projects to get work done.
- To fork a repository in Stash:
- a. Click the Fork button, found in the top right of the repository.
- b. Enter the project into which you would like to fork the repository.
- c. Enter the name of the repository - this will be used to create the forked repository's URL.
- d. Click the Fork repository button.
- See also: Using Forks in Stash
- 3. Create a local "clone" repository (of your "fork" of the original repository) on the computer you use for development
- (Optional) checkout a new branch based on the default branch, named in a way that relates to the work you're doing, e.g. "PROJ1-1234" if your JIRA project is named "PROJ1" and the work you're doing relates to issue 1234 on that project.
- 4. Make the necessary changes
- a. Edit
- b. commit
- c. (optional) pull changes from the original project, especially before pushing changes
- d. (optional) push changes back to your fork
- e. repeat until you've made all the changes you feel are necessary for this issue.
- 5. Push your changes up to the "fork" that you control
- Although steps c and d above are shown as optional, the last time through the loop (that repeats at step e) they are not optional: you must finally push all of the relevant changes up to the "fork" that you control.