docs: add contribution section, revise explanations by medubelko · Pull Request #6085 · canonical/snapcraft

medubelko · 2026-03-06T03:21:53Z

Rename and rewrite 'Contribute to this documentation'.
Add 'Contribute to development'.
Add 'About this documentation'.
Add second toctree.

I've followed the contribution guidelines.
I've signed the CLA.
I've successfully run make lint && make test.
I've added or updated any relevant documentation.
~~- [ ] I've updated the relevant release notes.~~

- Rename and rewrite 'Contribute to this documentation'. - Add 'Contribute to development'. - Add 'About this documentation'. - Add second toctree.

medubelko

@jahn-junior @lengau @mr-cal @bepri This isn't quite finished but it's more than a draft. In the interest of time, I'd like you to take a look the way this is organised and structured (pages, headings, order) and see how you feel about it. The main details are the same as in the existing CONTRIBUTING.md, so there shouldn't be any surprises.

@asanvaq Rockcraft shares the same governance and process, so its contribution pages ought to have the same shape as this. Please use this as a template if you'd like to get started.

medubelko · 2026-03-06T03:25:38Z

docs/contribute/development.rst

+``issue-235-add-string-sanitizer``.
+
+
+Develop


This section will be of most interest to @lengau, @mr-cal, and @bepri. We need to keep it as short as possible, ideally to five paragraphs or half a fold.

I'm most interested in whether it feels complete, and whether there's something we can trim.

medubelko · 2026-03-06T03:26:01Z

docs/contribute/development.rst

+Snapcraft is amenable to code generated with LLM assistance. Generating code is a time
+saver, but like all code it needs testing and careful review. An LLM doesn't absolve you
+of responsibility -- you are ultimately responsible for the code in your work.


I expect many revisions will come to this, so please consider this a best first effort.

In the medium-term, I think the simplest way to cut through the friction is to add a todo item for LLM disclosure to the PR template.

medubelko · 2026-03-06T03:30:50Z

docs/contribute/development.rst

+
+    When combining commit types, select the highest-ranked type that fits:
+
+    - :vale-ignore:`ci`


Not working because of an upstream bug.

Fix: canonical/documentation-style-guide#184

mr-cal · 2026-03-06T15:45:24Z

docs/contribute/development.rst

+working on snaps.
+
+
+Bounties


I think we can drop this, given that we're sunsetting the bounty program.

mr-cal · 2026-03-06T15:54:40Z

docs/contribute/development.rst

+
+    make test
+
+Running all tests can take a very long time, in some cases an hour.


This PR is landing on main and we'll be removing tests/legacy/unit on main next month. The time to run make test is going to drop to a few minutes or less (55 seconds on my system), so this notice may not be needed.

mr-cal · 2026-03-06T16:06:26Z

docs/contribute/documentation.rst

+Commit early and often. It's normal to make multiple commits for a single piece of work,
+especially when you come back to review it later. It's a good practice to get into to
+keep your changes safe.
+
+Committing triggers the pre-commit hook, which runs autoformatters. If any files were
+autoformatted, re-add them and redo the commit.


This is slightly different than the help in the develop section and I think I prefer this version of it better. Unless you intentionally made them different?

mr-cal · 2026-03-06T16:07:19Z

docs/contribute/documentation.rst

+after. **After the PR is approved, there may be a delay before merge.** The maintainers
+might need time to coordinate the PR with other development on the project.
+
+After approval, **don't** force-push to your branch. It's difficult for the maintainers


I like the emphasis here too, any reason not to put it in the dev page?

mr-cal · 2026-03-06T16:09:22Z

docs/contribute/development.rst

+    .. tab-item:: With HTTPS
+
+        If you don't authenticate with SSH, clone with `HTTPS
+        <https://docs.github.com/en/get-started/git-basics/about-remote-repositories#cloning-with-https-urls>`_


Suggested change

<https://docs.github.com/en/get-started/git-basics/about-remote-repositories#cloning-with-https-urls>`_

<https://docs.github.com/en/get-started/git-basics/about-remote-repositories#cloning-with-https-urls>`__

mr-cal · 2026-03-06T16:09:31Z

docs/contribute/development.rst

+    .. tab-item:: With SSH
+
+        If you authenticate your GitHub account with `SSH
+        <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_,


Suggested change

<https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_,

<https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`__,

mr-cal · 2026-03-06T16:11:17Z

docs/contribute/development.rst

+Snapcraft has 10-year long-term support commitments. All changes must be
+backward-compatible unless stated otherwise in the issue.
+
+All nontrivial changes must accompanied by new or updated tests. The Snapcraft test


Suggested change

All nontrivial changes must accompanied by new or updated tests. The Snapcraft test

All nontrivial changes must be accompanied by new or updated tests. The Snapcraft test

mr-cal · 2026-03-06T16:14:23Z

docs/contribute/index.rst

+
+.. code-block:: bash
+
+    snap install snapcraft_<instance> --channel <channel-name>


This may warrant a link to https://snapcraft.io/docs/explanation/how-snaps-work/parallel-installs/, since it will fail if the user hasn't configured snapd.

mr-cal · 2026-03-06T16:15:04Z

docs/contribute/development.rst

+        .. code-block:: bash
+
+            git fetch upstream
+            git switch -c <new-branch-nameupstream/hotfix/<current-release>


Suggested change

git switch -c <new-branch-nameupstream/hotfix/<current-release>

git switch -c <new-branch-name> upstream/hotfix/<current-release>

mr-cal · 2026-03-06T16:22:18Z

docs/contribute/development.rst

+Snapcraft has 10-year long-term support commitments. All changes must be
+backward-compatible unless stated otherwise in the issue.


What do you think about clarifying our commitment is per-base? Or that we can't make changes that require users to update their snaps for stable bases?

Here's a great example of the expectation I'd like to document: #5514 (comment)

medubelko added 3 commits March 5, 2026 14:49

chore(deps): add dependency sphinx-related-links >=0.1.1

2f090ea

chore(deps): update dependency canonical-sphinx to ~=0.6

78b7ba9

docs: add 'contribute' section

79578ee

- Rename and rewrite 'Contribute to this documentation'. - Add 'Contribute to development'. - Add 'About this documentation'. - Add second toctree.

medubelko requested review from a team, bepri and mr-cal as code owners March 6, 2026 03:21

medubelko commented Mar 6, 2026

View reviewed changes

mr-cal reviewed Mar 6, 2026

View reviewed changes


		When combining commit types, select the highest-ranked type that fits:

		- :vale-ignore:`ci`


		make test

		Running all tests can take a very long time, in some cases an hour.

	<https://docs.github.com/en/get-started/git-basics/about-remote-repositories#cloning-with-https-urls>`_
	<https://docs.github.com/en/get-started/git-basics/about-remote-repositories#cloning-with-https-urls>`__

	<https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_,
	<https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`__,

	All nontrivial changes must accompanied by new or updated tests. The Snapcraft test
	All nontrivial changes must be accompanied by new or updated tests. The Snapcraft test


		.. code-block:: bash

		snap install snapcraft_<instance> --channel <channel-name>

	git switch -c <new-branch-nameupstream/hotfix/<current-release>
	git switch -c <new-branch-name> upstream/hotfix/<current-release>

		Snapcraft has 10-year long-term support commitments. All changes must be
		backward-compatible unless stated otherwise in the issue.

		``issue-235-add-string-sanitizer``.


		Develop

Conversation

medubelko commented Mar 6, 2026

Uh oh!

medubelko left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants