Improve contributing docs aka hacking #57645

waynew · 2020-06-11T23:00:16Z

@barbaricyawps here's my update!

Closes #53633

See the pretty one here: https://github.com/waynew/salt/blob/improve-contributing-docs/HACKING.rst

HACKING.md

s0undt3ch

Why do we repeat content?

HACKING.md

HACKING.rst

HACKING.md

HACKING.rst

HACKING.md

ScriptAutomate

EDIT: Conversation with @sagetherage shows that my review comments here warrant a follow-up PR because of needed discussion with others down the pipeline around release generation where we need to ensure filename changes and deletion of files doesn't impact the build/release pipeline. I'm going to create a follow-up issue.

I'm wondering whether we can do the following:

Delete https://github.com/saltstack/salt/blob/master/.github/CONTRIBUTING.md (what GitHub is defaulting to as the contributing guide of the repo, in places like https://github.com/saltstack/salt/contribute and https://github.com/saltstack/salt/community)
Rename HACKING.md to CONTRIBUTING.md, so that GitHub automatically picks it up as the default contributing guide for people new to the repo, and so that people looking at the repo can automatically see that they should be looking at that (HACKING.md is unclear, especially since there co-exists a CONTRIBUTING.rst that this would also be replacing, I imagine)
Delete rst duplicate of HACKING.rst
Delete CONTRIBUTING.rst
Replace references of HACKING.rst and CONTRIBUTING.rst, where they appear in the repo, with HACKING.md (HACKING.md is not referenced by any other files in the repo):

# HACKING.rst -> CONTRIBUTING.md
pkg/suse/salt.spec:782:%doc LICENSE AUTHORS README.rst HACKING.rst README.SUSE
MANIFEST.in:4:include HACKING.rst

# CONTRIBUTING.rst -> CONTRIBUTING.md
MANIFEST.in:3:include CONTRIBUTING.rst

That, or we go with CONTRIBUTING.rst, and have the file get pulled in as the new contents of https://docs.saltstack.com/en/latest/topics/development/hacking.html (and rst include call), where we then will have the contributing guide in both the GitHub repo root (for easy access and reference via GitHub or source code), and in the Sphinx-generated documentation, without having duplicate files.

This would do some nice, significant cleanup and reduce a lot of confusion. Either it should be done within this PR, or in a PR directly following the merge of this PR.

barbaricyawps

I have more to say but I'm posting what I've reviewed so far.

HACKING.md

barbaricyawps · 2020-12-10T17:07:34Z

HACKING.md

+    brew update
+    brew install pyenv
+    brew install pyenv-virtualenv
+


Chore: We might want to ask @twangboy to write the section about how to set up a Windows environment.

Maybe open a separate issue for this chore and you can resolve this comment.

barbaricyawps · 2020-12-10T17:17:10Z

HACKING.md

+
+So you want to contribute to the Salt project? Excellent! You can help in a
+number of ways:
+


NOTE: I use the conventional comments method of PR reviewing.

Chore: Let's define what contributing means and what kinds of contributions we're looking for. I'm a big fan of the All Contributors Project statement that advocates for "recognizing contributors to an open source project in a way that rewards each and every contribution, not just code."

I don't think this is actually on you to do this in this PR, which is why I marked it as a follow-up chore. We need to maybe need to add this to the Open agenda and discuss it and then document the decision here. We could even go so far as considering adding the All Contributor's bot to our project, but that would require an SEP for sure. Could you help me open a ticket it or add it to the appropriate agenda and make sure I'm invited wherever that discussion occurs?

HACKING.md

waynew · 2020-12-17T22:17:56Z

Let's try this one 👍

ScriptAutomate · 2020-12-23T23:42:14Z

doc/topics/development/contributing.rst

+If the value is less than 2047, you should increase it with:

-SaltStack uses several labeling schemes to help facilitate code contributions
-and bug resolution. See the :ref:`Labels and Milestones
-<labels-and-milestones>` documentation for more information.
+::

-Mentionbot
----------
+   ulimit -n 2047
+   # For c-shell:
+   limit descriptors 2047


I did an audit of other open PRs, just in case there may need to be additional edits here, and I noticed this in #56391:

https://github.com/saltstack/salt/pull/56391/files?file-filters%5B%5D=.rst#diff-d4ef981b7725173c30d3e321db8d335dbf3419243e13699514cd1efad2d9f094R244-R247

The ulimit value is being adjusted to 3072. I'm not sure whether this is required or not, as I haven't gone this deep into the development where I was needing to adjust my ulimit -n value away from my dev system default of 1024 to 2047 or greater.

Whatever we decide on that (to update the value or not), we could actually close out #56391 because the rest of that PR is specific to Python 2, which is no longer supported by current versions of Salt. I've closed out #58128 as this PR will also supersede the need for it.

barbaricyawps

Praise: I'm loving this so much, Wayne. Gigantic improvement over the old style.

Summary: I have some minor quibbles that need to be resolved before I will feel comfortable giving my final approval. All of them are very quick fixes.

barbaricyawps · 2021-01-06T23:35:49Z

doc/topics/development/contributing.rst

+`Git <https://git-scm.com/>`__, a common version control tool used
+across many open source projects, and is necessary for contributing to
+salt. For an introduction to Git, watch `Salt Docs Clinic - Git For the
+True


Nitpick (blocking): I recommend always capitalizing Salt.

barbaricyawps · 2021-01-06T23:37:59Z

doc/topics/development/contributing.rst

-Sending a GitHub pull request
-----------------------------
+Sweet! Now you’re ready to clone salt so you can start hacking away! If
+you get stuck at any point, check out the resources at the beginning of


Nitpick (blocking): I recommend always capitalizing Salt.

barbaricyawps · 2021-01-06T23:38:26Z

doc/topics/development/contributing.rst


-    .. code-block:: bash
+This creates a shallow clone of salt, which should be fast. Most of the
+time that’s all you’ll need, and you can start building out other


Nitpick (blocking): I recommend always capitalizing Salt.

barbaricyawps · 2021-01-06T23:39:59Z

doc/topics/development/contributing.rst

+enables us to run multiple different test configurations, as well as
+other common tasks. You can think of it as Make with superpowers.
+Pre-commit does what it sounds like - it configures some Git pre-commit
+hooks to run ``black`` for formatting, ``isort`` for keeping our imports


Minor nitpick (non-blocking): Can you change the dash to a colon to satisfy my inner grammar nerd, please? :)

"Pre-commit does what it sounds like: it configures some Git pre-commit.."

barbaricyawps · 2021-01-06T23:40:54Z

doc/topics/development/contributing.rst

-    .. code-block:: bash
+.. warning::
+    Currently there is an issue with the pip-tools-compile pre-commit hook on windows.
+    The details around this issue are included here:


Nitpick (blocking): Please capitalize Windows. (But for the record, I care more about it for Salt than Windows.)

barbaricyawps · 2021-01-06T23:48:33Z

doc/topics/development/contributing.rst

+The first time this will take a while because there are a *lot* of
+modules. Maybe you should go grab some dessert if you already finished
+that sandwich. But once Sphinx is done building the docs, python should
+launch your default browser with the URL


Nitpick (blocking): I recommend capitalizing Python.

In this case I'll disagree: it's python the executable, not Python the language, that's launching the browser.

Sounds good to me. I'll defer to you. :)

barbaricyawps · 2021-01-06T23:49:41Z

doc/topics/development/contributing.rst

-    https://help.github.com/en.
+If your change is a doc-only change, you can go ahead and commit/push
+your code and open a PR. You can indicate that it’s a doc-only change by
+adding ``[Documentation]`` to the title of your PR. Otherwise you’ll


Minor nitpick (non-blocking): Can you say "docs-only" instead with the plural?

"If your change is a docs-only change, you can go ahead and commit/push
your code and open a PR. You can indicate that it’s a docs-only change by..."

barbaricyawps · 2021-01-06T23:51:34Z

doc/topics/development/contributing.rst

----------------------
+If you’d rather not use ``kill``, you can have a couple of terminals
+open with your salt virtualenv activated and omit the ``--daemon``
+argument. Salt will run in the foreground, so you can just use ctrl+c to


Nitpick (blocking): I recommend capitalizing Salt here too. "...your Salt virtualenv..."

I'll disagree here too: I'm referring to the name of the virtualenv, salt.

I'll defer to you. That's fine.

barbaricyawps · 2021-01-06T23:57:53Z

doc/topics/development/contributing.rst

+And that’s all that would go into your file. When it comes to your
+commit message, it’s usually a good idea to add other information - what
+does a reviewer need to know about the change that you made? If someone
+isn’t an expert in this area, what will they need to know?



Formatting recommendation (non-blocking): I like putting things in bullet points when I have a list of two or more things. I recommend:

And that’s all that would go into your file. When it comes to your
commit message, it’s usually a good idea to add other information, such as

What does a reviewer need to know about the change that you made?

If someone isn’t an expert in this area, what will they need to know?

barbaricyawps · 2021-01-06T23:59:24Z

doc/topics/development/contributing.rst

+passing and we’re not in a code freeze, ideally your code will be merged
+that day. If you haven’t heard from your assigned reviewer, ping them on
+GitHub, `irc <https://webchat.freenode.net/#salt>`__, or Community
+Slack.



Question: Are you sure we can keep this commitment to review a PR in one business day? That hasn't been my experience when contributing to Salt and I just worry about making a commitment we can't keep.

The goal is that we should at least be able to leave some sort of feedback within a business day. That's definitely not been the case typically, but that's not because it can't be done - we just haven't prioritized it.

I like your "can-do" attitude. Feel free to leave this as-is. :)

waynew · 2021-01-07T21:21:47Z

@barbaricyawps got those cleaned up! 👍

barbaricyawps

@waynew , approved!

s0undt3ch suggested changes Jun 12, 2020

View reviewed changes

HACKING.md Outdated Show resolved Hide resolved

HACKING.md Outdated Show resolved Hide resolved

dwoz added Needs-Testcase PR needs test cases written, or the issue is about a bug/feature that needs test cases has-failing-test labels Jun 16, 2020

sagetherage assigned waynew Jul 7, 2020

sagetherage added the Documentation Relates to Salt documentation label Sep 1, 2020

dwoz removed the Needs-Testcase PR needs test cases written, or the issue is about a bug/feature that needs test cases label Sep 22, 2020

sagetherage changed the title ~~Improve contributing docs~~ Improve contributing docs aka hacking Oct 26, 2020

ScriptAutomate mentioned this pull request Dec 7, 2020

[BUG] Installing Salt for development docs out of date #58516

Closed

waynew added 2 commits December 9, 2020 11:47

Hacking in markdown

efda781

Hacking draft in rst

81dc988

waynew force-pushed the improve-contributing-docs branch from 2e122df to 81dc988 Compare December 9, 2020 20:29

waynew marked this pull request as ready for review December 9, 2020 20:31

waynew requested a review from a team as a code owner December 9, 2020 20:31

waynew requested review from cmcmarrow and removed request for a team December 9, 2020 20:31

waynew removed the has-failing-test label Dec 9, 2020

krionbsd previously approved these changes Dec 9, 2020

View reviewed changes

sagetherage added the Aluminium Release Post Mg and Pre Si label Dec 9, 2020

sagetherage requested review from s0undt3ch and ScriptAutomate December 9, 2020 21:29

s0undt3ch reviewed Dec 9, 2020

View reviewed changes

HACKING.md Outdated Show resolved Hide resolved

HACKING.md Outdated Show resolved Hide resolved

HACKING.md Outdated Show resolved Hide resolved

HACKING.rst Outdated Show resolved Hide resolved

ITJamie reviewed Dec 9, 2020

View reviewed changes

HACKING.md Outdated Show resolved Hide resolved

ITJamie reviewed Dec 9, 2020

View reviewed changes

HACKING.rst Outdated Show resolved Hide resolved

Missing changes

baf2f7e

waynew dismissed krionbsd’s stale review via baf2f7e December 10, 2020 00:56

s0undt3ch reviewed Dec 10, 2020

View reviewed changes

HACKING.md Outdated Show resolved Hide resolved

ScriptAutomate requested changes Dec 10, 2020

View reviewed changes

ScriptAutomate previously approved these changes Dec 10, 2020

View reviewed changes

ScriptAutomate mentioned this pull request Dec 10, 2020

[DOCS] Contributor Guide: Needed Review, Refresh, and Jumping Off Point #58703

Closed

barbaricyawps suggested changes Dec 10, 2020

View reviewed changes

This was referenced Dec 23, 2020

Contributing Docs do not mention changelog #56561

Closed

Update reference to requirements file for tests #58128

Closed

ScriptAutomate reviewed Dec 23, 2020

View reviewed changes

ScriptAutomate mentioned this pull request Dec 24, 2020

[WIP] Fix proxmox list images #58619

Closed

3 tasks

ScriptAutomate self-requested a review January 4, 2021 21:44

ScriptAutomate previously approved these changes Jan 4, 2021

View reviewed changes

ScriptAutomate mentioned this pull request Jan 4, 2021

[BUG] #52359 was fixed for develop, but not merged to master #58313

Closed

Merge branch 'master' into improve-contributing-docs

77a28b2

garethgreenaway requested review from barbaricyawps and s0undt3ch January 5, 2021 17:41

s0undt3ch previously approved these changes Jan 5, 2021

View reviewed changes

krionbsd self-requested a review January 6, 2021 07:57

krionbsd previously approved these changes Jan 6, 2021

View reviewed changes

barbaricyawps suggested changes Jan 7, 2021

View reviewed changes

waynew added 3 commits January 7, 2021 15:18

Merge 'salt/master' into improve-contributing-docs

973d112

Merge

02a1364

Implement Alyssa's suggestions

808e18e

waynew dismissed stale reviews from krionbsd, s0undt3ch, and ScriptAutomate via 808e18e January 7, 2021 21:20

barbaricyawps approved these changes Jan 7, 2021

View reviewed changes

bryceml and others added 2 commits January 8, 2021 06:42

Merge branch 'master' into improve-contributing-docs

c1cbde7

Merge branch 'master' into improve-contributing-docs

726f079

ScriptAutomate approved these changes Jan 8, 2021

View reviewed changes

krionbsd self-requested a review January 11, 2021 16:50

krionbsd approved these changes Jan 11, 2021

View reviewed changes

dwoz merged commit 66b4479 into saltstack:master Jan 11, 2021

ScriptAutomate mentioned this pull request Jan 14, 2021

Update to main concurrent package for the Python2 #56391

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve contributing docs aka hacking #57645

Improve contributing docs aka hacking #57645

waynew commented Jun 11, 2020 •

edited

Loading

s0undt3ch left a comment

ScriptAutomate left a comment •

edited

Loading

barbaricyawps left a comment

barbaricyawps Dec 10, 2020 •

edited

Loading

barbaricyawps Jan 7, 2021 •

edited

Loading

barbaricyawps Dec 10, 2020

waynew commented Dec 17, 2020

ScriptAutomate Dec 23, 2020

barbaricyawps left a comment

barbaricyawps Jan 6, 2021

barbaricyawps Jan 6, 2021

barbaricyawps Jan 6, 2021

barbaricyawps Jan 6, 2021

barbaricyawps Jan 6, 2021

barbaricyawps Jan 6, 2021

waynew Jan 7, 2021

barbaricyawps Jan 7, 2021

barbaricyawps Jan 6, 2021

barbaricyawps Jan 6, 2021

waynew Jan 7, 2021

barbaricyawps Jan 7, 2021

barbaricyawps Jan 6, 2021

barbaricyawps Jan 6, 2021

waynew Jan 7, 2021

barbaricyawps Jan 7, 2021

waynew commented Jan 7, 2021

barbaricyawps left a comment


		So you want to contribute to the Salt project? Excellent! You can help in a
		number of ways:

Improve contributing docs aka hacking #57645

Improve contributing docs aka hacking #57645

Conversation

waynew commented Jun 11, 2020 • edited Loading

s0undt3ch left a comment

Choose a reason for hiding this comment

ScriptAutomate left a comment • edited Loading

Choose a reason for hiding this comment

barbaricyawps left a comment

Choose a reason for hiding this comment

barbaricyawps Dec 10, 2020 • edited Loading

Choose a reason for hiding this comment

barbaricyawps Jan 7, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

waynew commented Dec 17, 2020

Choose a reason for hiding this comment

barbaricyawps left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

waynew commented Jan 7, 2021

barbaricyawps left a comment

Choose a reason for hiding this comment

waynew commented Jun 11, 2020 •

edited

Loading

ScriptAutomate left a comment •

edited

Loading

barbaricyawps Dec 10, 2020 •

edited

Loading

barbaricyawps Jan 7, 2021 •

edited

Loading