Skip to content

Commit

Permalink
Merge pull request #28 from cgay/dev
Browse files Browse the repository at this point in the history
doc: clarify changing optional package-level attributes
  • Loading branch information
cgay authored Apr 21, 2024
2 parents 7755a43 + 4949201 commit 86583a2
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 17 deletions.
35 changes: 19 additions & 16 deletions documentation/source/index.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. highlight:: shell

********************
Deft - The Dylan CLI
deft - The Dylan CLI
********************

The :program:`deft` command-line tool is intended to make Dylan development
Expand Down Expand Up @@ -62,9 +62,8 @@ Where are Packages Installed?
directory at the root of your workspace by default. However, you may choose to
install them globally with :command:`deft update --global`.

The package manager always caches `its catalog
<https://github.com/dylan-lang/pacman-catalog>`_ in the global location (per
user).
The package manager always caches `its catalog <pacman-catalog>`_ in the global
location (per user).

The global :file:`_packages` directory location is chosen based on environment
variables, in this order:
Expand Down Expand Up @@ -642,15 +641,15 @@ catalog.
Synopsis: ``deft publish <pacman-catalog-directory>``

.. note:: For now, until a fully automated solution is implemented, the publish
command works by modifying a local copy of the catalog so that you can
manually submit a pull request. This eliminates a lot of possibilities for
making mistakes while editing the catalog by hand.
command works by modifying a local copy of the `pacman-catalog`_ Git
repository and you must manually submit a pull request with the changes. In
a future release this manual step will be eliminated.

This command publishes a package associated with the current workspace. It
searches up from the current directory to find :file:`dylan-package.json`. Note
that this means you can't be in the root of a multi-package workspace. Once
you're satisfied that you're ready to release a new version of your package
(tests pass, doc updated, etc.) follow these steps:
searches up from the current directory to find
:file:`dylan-package.json`. *Note that this means you can't be in the root of a
multi-package workspace.* Once you're satisfied that you're ready to release a
new version of your package (tests pass, doc updated, etc.) follow these steps:

#. Update the ``"version"`` attribute in :file:`dylan-package.json` to be the
new release's version.
Expand All @@ -661,33 +660,37 @@ you're satisfied that you're ready to release a new version of your package
**Remember to** `deft update`_ **and re-run your tests if you change
deps!**

Push the above changes (if any) to your main branch.
Push the above changes, if any, to your main branch.

#. Make a new release on GitHub with a tag that matches the release version.
For example, if the ``"version"`` attribute in :file:`dylan-package.json`
is ``"0.5.0"`` the GitHub release should be tagged ``v0.5.0``.

#. Clone https://github.com/dylan-lang/pacman-catalog somewhere and create a
new branch named after your package. ::
new branch. ::

$ cd /tmp
$ git clone https://github.com/dylan-lang/pacman-catalog
$ cd pacman-catalog
$ git switch -t -c my-package

In the next step the `deft publish`_ command will make changes there for
you.
In the next step the `deft publish`_ command will make changes in this
directory for you.

#. Run :command:`deft publish /tmp/pacman-catalog`, pointing to where you
just cloned the pacman catalog.

#. Commit the changes to `pacman-catalog`_ and submit a pull request. The
tests to verify the catalog will be run automatically by the GitHub CI.
tests to verify the catalog will be run automatically by a GitHub workflow.

#. Once your PR has been merged, verify that the package is available in the
catalog by running :command:`deft install [email protected]`, substituting
your new package name and release version.

.. note:: If you remove `optional package attributes
<pacman.html#optional-package-attributes>`_ from
:file:`dylan-package.json` they will be removed from the catalog
entry for *all releases* of your package.

.. index::
single: deft status subcommand
Expand Down
5 changes: 4 additions & 1 deletion sources/pacman/catalog.dylan
Original file line number Diff line number Diff line change
Expand Up @@ -364,7 +364,10 @@ define function publish-release
if (cat-package)
// Include the releases from the existing package when we write the file.
// new-package was created by loading dylan-package.json, and doesn't have
// any of the existing releases in it.
// any of the existing releases in it. Doing it this way, instead of adding
// the new-package release and attributes to cat-package, allows optional
// package-level attributes to be removed by removing them from
// dylan-package.json.
for (rel in package-releases(cat-package))
add-release(new-package, rel);
end;
Expand Down

0 comments on commit 86583a2

Please sign in to comment.