{%
   include-markdown "../../common-subs/coming-soon.md"
   start="<!--coming-soon-start-->"
   end="<!--coming-soon-end-->"
%}

<!-- Code management
  Prow, Gh actions broken links, pr verifier, emoji in titles of prs, add issue to project. Add pr to project. Check spelling errors, wordlist.txt, 
Quay.io -->
# Code Management
Fork kubestellar into your own repo, create a local branch, set upstream to kubestellar, add and commit changes to local branch, and squash your commits

## Initial setup

### Fork the GitHub kubestellar repo into your own GitHub repo:
You can do this either 1: from the kubestellar GitHub website using the "Fork" button or 2: by using the git fork command from your local git command line interface, such as git bash.

copy the forked repo from GitHub to your local system by using the "git clone" command or by downloading the repository's zip file.

In your new local forked repo, set upstream to kubestellar main

check what your repository's remote settings are

```bash
git remote -v
```

### Set upstream to use kubestellar:

```bash
git remote add upstream git@github.com:kubestellar/kubestellar.git
```

For example:

```bash
$ git remote -v
origin  git@github.com:fileppb/kubestellar.git (fetch)
origin  git@github.com:fileppb/kubestellar.git (push)

$ git remote add upstream git@github.com:kubestellar/kubestellar.git

$ git remote -v
origin  git@github.com:fileppb/kubestellar.git (fetch)
origin  git@github.com:fileppb/kubestellar.git (push)
upstream        git@github.com:kubestellar/kubestellar.git (fetch)
upstream        git@github.com:kubestellar/kubestellar.git (push)

$ git fetch upstream
Enter passphrase for key '/c/Users/owner/.ssh/id_rsa':
remote: Enumerating objects: 60394, done.
remote: Counting objects: 100% (5568/5568), done.
remote: Compressing objects: 100% (255/255), done.
remote: Total 60394 (delta 4768), reused 5457 (delta 4706), pack-reused 54826
Receiving objects: 100% (60394/60394), 52.38 MiB | 3.25 MiB/s, done.
Resolving deltas: 100% (34496/34496), completed with 415 local objects.

$ git status

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean
```

## Ongoing contributions

### Prior to working on an issue

Ensure that your personal repository is up to date with the KubeStellar repository.
You can do this by opening your GitHub repository page, check that the selected branch is "main", and press the "sync fork" button.

### Select an issue to work on and create a local branch, 

Create a local branch for your work, preferably including the issue number in the branch name

for example if working on issue #11187, then you might name your local branch "issue-1187"

```bash
git checkout -b issue-1187
```

### As you work and change files, you should try to commit relatively small pieces of work, using the following commands

```bash
git add (there are several options you can specify for the git add command)

git commit -m "your message"

git push -u origin branch-name (-u sets upstream to origin which is your remote GitHub repository)
```

### When you have completed your work and tested it locally, then you should perform a squash of the git commits to make the upcoming push request more manageable.

To perform a squash, checkout the branch you want to squash,
1. use the "git log" command to see the history of commits to the branch
2. Count the number of commits you want to squash
3. use the "git rebase -i HEAD~n" where n is the number of commits you would like to squash together. (There are other ways to do this)
4. The text editor you have configured to use with git should automatically open your source and you will see a list of commits preceded by "pick". Leaving the first "pick" as it is, replace the remaining "pick"s with "squash"es. 
5. Save the text file and exit the editor.
6. The text editor will open again to let you edit comments for your new squashed commit.
7. Make your edits if any and save and exit the file.
The commits will then be squashed into one commit.

### When you are done with the squash, push your changes to your remote branch. You can either:

```bash
git push -u origin <branch-name>

or 

git push --force-with-lease
```

Note: if using the git push -u origin <branch-name> command, the -u only needs to specified the first time you push. It will set tracking for subsequent pushes to the branch. On the other hand, keeping the -u in the command does no particular harm.

## Run Actions (automated workflow tests) manually in your personal GitHub repository

1. Select the "Actions" tab toward the upper left of your GitHub personal web page. This will cause a list of Actions to show.
2. Select the action you wish to execute from the list of Actions. For example you might chose "docs-ecutable - example1".
Note: docs-ecutable should be described in a separate section. But in a nutshell it's a Continuous Integration automation technique of embedding scripts and data within the body of documentation, and then parsing and executing those scripts which in turn interpret and execute source code from a branch that you designate. It's somewhat similar to Travis. So the Action "docs-ecutable - example1" executes scripts and data embedded within the documentation for the Example 1 scenario, described in the KubeStellar documents. Those scripts will run using the source code pointed to by the next step, step 3.
3. Select the source code branch you wish to exercise by following the next 3 steps:
  1. select the black and white "Run Workflow" on the right side of your GitHub web page. This will open a dialog box.
  2. within the dialog box, select the branch you wish to exercise by opening the dropdown labeled "use workflow from"
  3. within the dialog box, select the green "Run Workflow" button 
Your selected Action workflow will execute and the results will be available when it completes.  

## Create a Pull Request (PR) from your GitHub repo branch in order to request review and approval from the KubeStellar team

Take a look at [the contribution guidelines](../documentation/contributing-inc.md).

You can create a Pull Request from your GitHub web repository by selecting the "Compare & pull request" button.

You will be presented with a GitHub web page titled Comparing Changes, which allows you to enter metadata regarding your pull request

Reference the issue you are addressing ( add #issue-number)
The title of the PR must start with a special character (emoji) that
indicates the type of the PR. It must be one of the following:

- ⚠ (indicates breaking change)
- ✨ (indicates non-breaking feature)
- 🐛 (indicates patch fix)
- 📖 (indicates documentation)
- 🚀 (indicates release)
- 🌱 (indicates infra, tests, or other changes)
Complete the summary description field
Complete the Related issue field by inserting the issue number preceded by the # character, for example "#1187"
Decide whether this is a draft PR or if it's ready for review, and select the option you want by expanding on the Create Pull Request button.
Assign a label to the PR from the available list of labels (a drop down list on the right side of the web page)

## KubeStellar CI pipeline

### Prow CI jobs

KubeStellar Prow CI jobs run inside containerized environments.
Required tooling such as Python is provided by the container image
itself, rather than being downloaded dynamically during job execution
(e.g., Python 3.14). This improves CI reliability and consistency.

See: https://docs.prow.k8s.io/docs/overview/


Prow (https://docs.prow.k8s.io/docs/overview/)

### Container builds for Galaxy components

Galaxy components such as `shadow-pods` and `mc-scheduler` use Dockerfiles
that reflect their actual Go source layout rather than template
structures.

- The `shadow-pods` Dockerfile copies the full `cmd/` and `internal/`
  directories and builds the binary from `./cmd/shadow-pods`.
- The `mc-scheduler` Dockerfile copies the full `cmd/`, `internal/`, and
  `pkg/` directories and builds the binary from `./cmd/mc-scheduler`.

This alignment with the real source tree prevents container build
failures and ensures the Container Image Scanning workflow completes
successfully for all components.

#### Argo CD integration tests

KubeStellar includes gated integration tests that validate the installation
and readiness of Argo CD in a real Kubernetes cluster.

These tests run as part of the Prow CI pipeline and verify that:
- Argo CD can be installed successfully using Helm
- Core Argo CD components become healthy and ready
- KubeStellar continues to operate correctly alongside Argo CD

Because these are real cluster integration tests, they may take longer
to complete than unit tests and are enforced as required checks for
pull requests.
