diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 65f9f309..2c31e1d8 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -22,7 +22,7 @@ Release 0.11.0 (unreleased) * Don't make metadata file part of diff (#267) * Fix unneeded project prefix in SVN diffs (#888) * Add more tests and documentation for patching (#888) -* Restrict ``src`` to string only in schema (#889) +* Restrict ``src`` to string only in schema (#888) * Don't consider ignored files for determining local changes (#350) Release 0.10.0 (released 2025-03-12) diff --git a/README.md b/README.md index f7320850..388263f3 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,7 @@ problem, but not in a VCS-agnostic way or completely user-friendly way. We want self-contained code repositories without any hassle for end-users. Dfetch must promote upstreaming changes, but allow for local customizations. The problem is described thoroughly in [managing external dependencies](https://embeddedartistry.com/blog/2020/06/22/qa-on-managing-external-dependencies/) and sometimes -is also known as [*vendoring*](https://stackoverflow.com/questions/26217488/what-is-vendoring). -See [vendoring](https://dfetch.readthedocs.io/en/latest/vendoring.html) for more information about vendoring. +is also known as [*vendoring*](https://dfetch.readthedocs.io/en/latest/vendoring.html). Other tools that do similar things are ``Zephyr's West``, ``CMake ExternalProject`` and other meta tools. See [alternatives](https://dfetch.readthedocs.io/en/latest/alternatives.html) for a complete list. diff --git a/doc/alternatives.rst b/doc/alternatives.rst index 18284524..e0b03d8f 100644 --- a/doc/alternatives.rst +++ b/doc/alternatives.rst @@ -1,12 +1,15 @@ -.. Dfetch documentation master file + Alternatives ============ The problem *Dfetch* tries to solve isn't new. There are other tools doing the same. In making a proper choice, see the below alternatives. -These alternatives could all be used to use *source* code from another project as part -of your project. +There are many alternatives, each with slightly different approaches or focuses: some are designed to manage +multiple repositories together, some are specialized in :ref:`vendoring` code into your project, and others provide +build-system or version-control-specific helpers. + +Below is a list of notable tools along with their supported version control systems, platforms, and compatibility. ========================= ===== ===== ========= ======= =================== ======================= Name Git SVN Windows Linux Language Agnostic Build System Agnostic @@ -65,7 +68,7 @@ Dfetch_ ✔ ✔ ✔ ✔ ✔ .. _`Braid`: https://github.com/cristibalan/braid .. _`CGet`: https://github.com/pfultz2/cget -.. _`CMAke ExternalProject`: https://cmake.org/cmake/help/latest/module/ExternalProject.html +.. _`CMake ExternalProject`: https://cmake.org/cmake/help/latest/module/ExternalProject.html .. _`Combo-layer`: https://wiki.yoctoproject.org/wiki/Combo-layer .. _`CPM.cmake`: https://github.com/cpm-cmake/CPM.cmake .. _`CPPAN`: https://github.com/cppan/cppan diff --git a/doc/conf.py b/doc/conf.py index f2834181..651071c7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,6 +40,7 @@ "sphinx-jsonschema", "sphinxcontrib.programoutput", "sphinx_tabs.tabs", + "sphinx_autoissues", ] # Add any paths that contain templates here, relative to this directory. @@ -92,6 +93,10 @@ # Suppress warnings about duplicate labels from argparse directive suppress_warnings = ["autosectionlabel.manual"] +# Options for sphinx-autoissues +issuetracker = "github" +issuetracker_project = "dfetch-org/dfetch" + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/doc/contributing.rst b/doc/contributing.rst index 8b9fbb75..c01580e8 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Contributing ============ diff --git a/doc/examples.rst b/doc/examples.rst deleted file mode 100644 index f7d74cda..00000000 --- a/doc/examples.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. Dfetch documentation master file - -Examples -============ - -Real world projects -------------------- - -Here are some links to example projects using *Dfetch*. - -- `Dfetch`: https://github.com/dfetch-org/dfetch -- `ModbusScope`: https://github.com/ModbusScope/ModbusScope - -Internally we use *Dfetch* for various projects and uses. diff --git a/doc/getting_started.rst b/doc/getting_started.rst index 85827a5a..5620abe6 100644 --- a/doc/getting_started.rst +++ b/doc/getting_started.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Getting Started =============== diff --git a/doc/index.rst b/doc/index.rst index d8c12e1d..7715f5f5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + .. meta:: :description: Dfetch is a VCS-agnostic tool that simplifies dependency management by retrieving @@ -28,6 +28,7 @@ .. toctree:: :maxdepth: 2 + installation getting_started manifest manual @@ -35,7 +36,6 @@ contributing changelog alternatives - examples vendoring legal internal @@ -46,37 +46,19 @@ Dfetch - *a source-only no-hassle project-dependency aggregator* What is Dfetch? --------------- -We needed a dependency manager that was flexible enough to retrieve dependencies as plain text +We make products that can last 15+ years; because of this we want to be able to have all sources available +to build the entire project from source without depending on external resources. +For this, we needed a dependency manager that was flexible enough to retrieve dependencies as plain text from various sources. `svn externals`, `git submodules` and `git subtrees` solve a similar -problem, but not in a vcs agnostic way or completely user friendly way. +problem, but not in a VCS-agnostic way or completely user-friendly way. We want self-contained code repositories without any hassle for end-users. Dfetch must promote upstreaming changes, but allow for local customizations. +The problem is described thoroughly in `managing external dependencies `_ and sometimes +is also known as :ref:`vendoring`. -Other tools that do similar things are `Zephyr's West`, `CMake ExternalProject` and other meta tools. +Other tools that do similar things are ``Zephyr's West``, ``CMake ExternalProject`` and other meta tools. See :ref:`alternatives` for a complete list. -Installation ------------- -`Dfetch` is a python based cross-platform cli tool. - -Install the latest release with: - -.. code-block:: - - pip install dfetch - -Or install the latest version from the main branch: - -.. code-block:: - - pip install https://github.com/dfetch-org/dfetch/archive/main.zip - -Once installed dfetch output can be seen. - -.. code-block:: - - dfetch --version - Basic usage ----------- diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 00000000..4f7df598 --- /dev/null +++ b/doc/installation.rst @@ -0,0 +1,86 @@ + + + +Installation +============ + +From pip +-------- + +If you are using python you can install the latest release with: + +.. code-block:: bash + + pip install dfetch + +Or install the latest version from the main branch: + +.. code-block:: bash + + pip install git+https://github.com/dfetch-org/dfetch.git#egg=dfetch + +Binary distributions +-------------------- + +Each release on the `releases page `_ +provides pre-built installers for all major platforms, so no compilation is required. + +Each installer package has a name in the format ``-``. + +- ```` shows the software version: + + - If it includes ``dev``, it is a development release (for testing). + - If it is only numbers (e.g. ``0.11.0``), it is an official release. + +- ```` indicates the system the installer is for: ``nix`` (Linux), ``osx`` (Mac), or ``win`` (Windows). + +The version is automatically determined from the project and used to name the installer files. + +.. tabs:: + + .. tab:: Linux + + Download the ``.deb`` or ``.rpm`` package from the releases page and install it. + + Debian / Ubuntu (``.deb``): + + .. code-block:: bash + + sudo dpkg -i dfetch--nix.deb + + RPM-based distributions (``.rpm``): + + .. code-block:: bash + + sudo dnf install dfetch--nix.rpm + # or + sudo rpm -i dfetch--nix.rpm + + .. tab:: macOS + + Download the ``.pkg`` package from the releases page and install it. + + .. code-block:: bash + + sudo installer -pkg dfetch--osx.pkg -target / + + .. tab:: Windows + + Download the ``.msi`` installer and install by double-clicking or use: + + .. code-block:: powershell + + msiexec /i dfetch--win.msi + + Uninstalling can be done through the regular Add/Remove programs section. + +Validating Installation +----------------------- + +Run the following command to verify the installation + +.. code-block:: bash + + dfetch environment + +.. asciinema:: asciicasts/environment.cast diff --git a/doc/legal.rst b/doc/legal.rst index 70cafc9f..5e36a740 100644 --- a/doc/legal.rst +++ b/doc/legal.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Legal ===== diff --git a/doc/manifest.rst b/doc/manifest.rst index 811c1867..cde2426e 100644 --- a/doc/manifest.rst +++ b/doc/manifest.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Manifest ======== diff --git a/doc/manual.rst b/doc/manual.rst index 43571841..d3332349 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Manual ====== diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index 2f130808..0d26c3d2 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -1,25 +1,60 @@ -.. Dfetch documentation master file + Troubleshooting =============== -Although we do our best, *Dfetch* can always do something unexpected. -A great deal of *Dfetch* functionality is dependent on plain-old command line commands. +Sometimes *Dfetch* may not behave as expected. This is could be because it relies on +standard command-line tools such as ``git`` to be available on your system. This section will help you +diagnose problems and understand what is happening behind the scenes. + +Step 1: Check your environment +------------------------------ + +Before anything else, it's helpful to see which tools *Dfetch* can detect on your system. +This shows missing or incompatible dependencies. Run: + +.. code-block:: bash + + dfetch environment + +Compare the output to the expected tools your commands require. + +.. asciinema:: asciicasts/environment.cast + +Step 2: Use verbose mode +------------------------ -First of all, it is important to see what tools the system has. -This can be seen with :ref:`dfetch environment`. +If a specific *Dfetch* command gives unexpected results, run it with the ``-v`` flag +to see exactly what *Dfetch* is doing: -Each command *Dfetch* performs and its result can be shown with increasing the verbosity -with the `-v` flag. For example, if an :ref:`dfetch import` is giving strange results, re-run it with:: +.. code-block:: bash dfetch -v import -Reporting issues ----------------- -We are glad to help, if you you are stuck, either create an issue_ on github or contact us through gitter_! +Verbose output shows each command *Dfetch* executes and its result, making it easier +to spot errors, missing tools, or other issues. +There can be various issues with for instance contacting or authenticating with the remote +repository or with local settings. By running the ``git`` or ``svn`` command in isolation +the issue can be shown more clearly. + +Step 3: Reporting issues +------------------------ + +If you cannot resolve a problem, we're happy to help! Check for any existing `GitHub Issues`_. +When reporting an issue, please include: + +1. The output of ``dfetch environment`` +2. The verbose output of the failing command (``dfetch -v ``) +3. Your operating system and shell information + +You can report issues via: + +- `GitHub Issues`_ +- `Gitter`_ community chat + +.. _`GitHub Issues`: https://github.com/dfetch-org/dfetch/issues +.. _`Gitter`: https://gitter.im/dfetch-org/community -.. _issue: https://github.com/dfetch-org/dfetch/issues -.. _gitter: https://gitter.im/dfetch-org/community Security issues ---------------- @@ -29,5 +64,5 @@ You can report issues by opening a confidential issue via `GitHub Security Advis `GitHub's private vulnerability reporting`_ for more info. If you have no contact please contact us through the mail listed in the pyproject.toml. -.. _`GitHub Security Advisories`: https://github.com/dfetch/dfetch/security/advisories +.. _`GitHub Security Advisories`: https://github.com/dfetch-org/dfetch/security/advisories .. _`GitHub's private vulnerability reporting`: https://docs.github.com/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) diff --git a/doc/vendoring.rst b/doc/vendoring.rst index 98ec399b..9e709590 100644 --- a/doc/vendoring.rst +++ b/doc/vendoring.rst @@ -1,7 +1,7 @@ -.. Dfetch documentation master file -Vendoring Dependencies -====================== + +Vendoring +========= Vendoring is the practice of copying the source code of another project directly into your own project's repository. Instead of relying on a package manager to @@ -322,6 +322,16 @@ Real-world projects using vendoring - `Kubernetes - (Go) `_ - `Cargo - (Rust) `_ +Real world projects using Dfetch +-------------------------------- + +Here are some links to example projects using *Dfetch*. + +- `Dfetch`: https://github.com/dfetch-org/dfetch +- `ModbusScope`: https://github.com/ModbusScope/ModbusScope + +Internally we use *Dfetch* for various projects and uses. + Further Reading --------------- diff --git a/pyproject.toml b/pyproject.toml index 38afeeef..e0c1fc3e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -98,6 +98,7 @@ docs = [ 'sphinx-jsonschema==1.19.2', 'sphinxcontrib-programoutput==0.18', 'sphinx-tabs==3.4.7', + 'sphinx-autoissues==0.0.1', ] test = ['pytest==8.4.2', 'pytest-cov==7.0.0', 'behave==1.3.3'] casts = ['asciinema==2.4.0']