chore: import upstream snapshot with attribution

docs/dev/contribute.md

@@ -0,0 +1,147 @@
+# Contribute to SWE-agent
+
+!!! tip "Formatting change"
+    We've recently added automated formatting to our code base.
+    If you are dealing with merge-conflicts when opening a PR or updating your fork,
+    please first install `pre-commit` and run `pre-commit run --all-files` and try again.
+
+{%
+    include-markdown "../../CONTRIBUTING.md"
+    start="<!-- INCLUSION START -->"
+    end="<!-- INCLUSION END -->"
+%}
+
+Wanna do more and actually contribute code? Great! Please see the following sections for tips and guidelines!
+
+## Development repository set-up
+
+Please install the repository from source, following our [usual instructions](../installation/source.md) but add the `[dev]` option to the `pip` command (you can just run the command again):
+
+```bash
+pip install -e '.[dev]'
+```
+
+Then, make sure to set up [`pre-commit`](https://pre-commit.com):
+
+```bash
+# cd to our repo root
+pre-commit install
+```
+
+`pre-commit` will check for formatting and basic syntax errors before your commits.
+
+!!! tip "Autofixes"
+    Most problems (including formatting) will be automatically fixed.
+    Therefore, if `pre-commit`/`git commit` fails on its first run, simply try running it a second time.
+
+    Some more autofixes can be enabled with the `--unsafe-fixes` option from [`ruff`](https://github.com/astral-sh/ruff):
+
+    ```bash
+    pipx run ruff check --fix --unsafe-fixes
+    ```
+
+## Running tests
+
+We provide a lot of tests that can be very helpful for rapid development.
+Run them with
+
+```bash
+pytest
+```
+
+Some of the tests might be slower than others. You can exclude them with
+
+```bash
+pytest -m "not slow"
+```
+
+You can run all tests in parallel with `pytest-xdist`:
+
+```bash
+pytest -n auto
+```
+
+If you are using VSCode, you might want to add the following two files:
+
+<details>
+<summary><code>.vscode/launch.json</code></summary>
+
+```json
+--8<-- "docs/dev/vscode_launch.json"
+```
+</details>
+
+<details>
+<summary><code>.vscode/settings.json</code></summary>
+
+```json
+--8<-- "docs/dev/vscode_settings.json"
+```
+</details>
+
+## Debugging
+
+We recommend to install `pdbpp` for some improved debugger features:
+
+```bash
+pip install pdbpp
+```
+
+Set breakpoints with `breakpoint()` and then run `sweagent` with `pdb`:
+
+```bash
+pdb -m sweagent <command> -- <more command line arguments> # (1)!
+```
+
+1. Note the `--` before the options passed to sweagent. This is to separate
+  options passed to `pdb` from those that are passed to `sweagent`.
+
+
+When working on a test that fails, you can use
+
+```
+pytest -k name_of_test -s --capture=no --log-cli-level=DEBUG
+```
+
+to see all debug output from the agent.
+
+## Tips for pull requests
+
+* If you see a lot of formatting-related merge conflicts, please see [here](formatting_conflicts.md).
+* Please open separate PRs for separate issues. This makes it easier to incorporate part of your changes.
+* It might be good to open an issue and discuss first before investing time on an experimental feature.
+* Don't know where to get started? Look for issues marked [👋 good first issue][gfi] or [🙏 help wanted][help_wanted]
+* When changing the behavior of the agent, we need to have some indication that it actually improves the success rate of SWE-agent.
+  However, if you make the behavior optional without complicating SWE-agent (for example by providing new [commands](../config/tools.md)),
+  we might be less strict.
+* Please add simple unit tests or integration tests wherever possible. Take a look in the [tests directory](https://github.com/SWE-agent/SWE-agent/tree/main/tests)
+  for inspiration. We emphasize simple easy-to-write tests that get a lot of coverage.
+
+[gfi]: https://github.com/SWE-agent/SWE-agent/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22%F0%9F%91%8B+good+first+issue%22+
+[help_wanted]: https://github.com/SWE-agent/SWE-agent/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22%F0%9F%99%8F+help+wanted%22
+
+## Building the documentation <a name="mkdocs"></a>
+
+Simply run
+
+```bash
+# cd repo root
+mkdocs serve
+```
+
+and point your browser to port 8000 or click one of the links in the output.
+
+## Diving into the code
+
+<div class="grid cards">
+  <a href="../reference/" class="nav-card-link">
+    <div class="nav-card">
+      <div class="nav-card-header">
+        <span class="material-icons nav-card-icon">settings</span>
+        <span class="nav-card-title">Code structure and reference</span>
+      </div>
+      <p class="nav-card-description">Read the reference for more information on our code.</p>
+    </div>
+  </a>
+</div>
+{% include-markdown "../_footer.md" %}

docs/dev/formatting_conflicts.md

@@ -0,0 +1,65 @@
+On May 28th, 2024, we introduced automated formatting with `ruff-format` and `pre-commit`. This changed almost every file in the project.
+If you forked or branched off before these changes and now try to synchronize your fork/branch with `SWE-agent/SWE-agent:main`, you will
+see a lot of merge conflicts.
+
+To solve this, you need to apply the same formatting to your code. Here's how you can do it.
+
+First let's add the official remote (if it exists, you've probably already added it and you can ignore the warning).
+
+```bash
+git remote add upstream https://github.com/SWE-agent/SWE-agent.git
+git fetch upstream
+```
+
+Now, you need the updated `pyproject.toml` and `.pre-commit-config.yaml` files.
+We can get them from `SWE-agent/SWE-agent:main`:
+
+```bash
+git checkout upstream/main -- .pre-commit-config.yaml pyproject.toml
+git commit -m "Update formatting instructions" --no-verify
+```
+
+Let's assume that your changes are on branch `FEATURE_BRANCH`, for example, if you've committed to `main`:
+
+```bash
+export FEATURE_BRANCH="main"
+```
+
+Next we create a copy of this branch (so we don't further modify it):
+
+```bash
+git branch "${FEATURE_BRANCH}_REBASED" "${FEATURE_BRANCH}"
+```
+
+And now comes the tricky bit: We rebase your changes on top of `upstream/main`, while applying
+the formatting fixes at every step:
+
+```bash
+git rebase upstream/main "${FEATURE_BRANCH}_REBASED" \
+  -Xtheirs \
+  --exec 'git reset --soft HEAD^; pre-commit run; pipx run ruff check --fix --unsafe-fixes; git add -u; git commit -C HEAD@{1} --no-verify'
+```
+
+!!! note "Understanding the last command"
+    Here's what is happening:
+
+    * `git rebase upstream/main "${FEATURE_BRANCH}_REBASED"`
+    applies every commit from `"${FEATURE_BRANCH}_REBASED"` on top of `upstream/main`.
+    * `-Xtheirs` tells git to always take _your_ changes for merge conflicts
+      (rather than the format changes).
+    * After every commit, the command from `--exec` is being called.
+        * `git reset --soft HEAD^` undos the `git commit` action (while leaving the
+          changes staged),
+        * then we apply the formatting, and
+        * finally we commit the
+          formatted changes again.
+
+!!! tip "Still merge conflicts?"
+    It's possible that there are non-formatting-related merge conflicts that you are encountering.
+    In this case, `git rebase` will stop every time it cannot resolve the conflict.
+    Simply fix the merge conflicts as you would normally do (edit the file, commit once done),
+    and then run `git rebase --continue`.
+
+You can now open a PR from `${FEATURE_BRANCH}_REBASED` or make it your new default branch.
+
+{% include-markdown "../_footer.md" %}

docs/dev/vscode_launch.json

@@ -0,0 +1,17 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Debug Tests",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "purpose": ["debug-test"],
+            "console": "integratedTerminal",
+            "env": {
+                "PYTEST_ADDOPTS": "--no-cov"
+            },
+            "justMyCode": false
+        }
+    ]
+}

docs/dev/vscode_settings.json

@@ -0,0 +1,12 @@
+{
+    "python.testing.pytestArgs": [
+        "sweagent",
+        "--cov=sweagent/",
+        "--cov-report=xml:cov.xml",
+        "-n", "auto",
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "git.ignoreLimitWarning": true
+}