Overhaul documentation and add contributing guide by choldgraf · Pull Request #86 · executablebooks/github-activity

choldgraf · 2023-03-01T15:37:27Z

This makes major updates to our documentation to add more information for contributors, and to make it easier to parse.

Adds a GitHub action that is dedicated to publishing to PyPI rather than being nested in tests.yml
Documents how to make a release
Adds a dedicated contributing and usage guide: closes Improve the docs and add contributing guide #85
Adds a changelog
Makes a few other quality of life improvements here and there

I'll get the tests passing, but wanted to get this up to confirm that @blink1073 and @minrk think this would be a useful addition to help others get started!

blink1073

Nice, sounds good!

blink1073 · 2023-03-02T16:08:25Z

docs/contribute.md

+1. **Bump the version in `__init__.py` and push it to master**.
+   We try to use [semver version numbers](https://semver.org/) but don't stress out about it too much.
+   - In your commit message use something like `RLS: vX.X.X`.
+   - Add a changelog to `CHANGELOG.md`[^1].


Maybe add a nox command to generate the new changelog entry, if only to print out on the console?

manics

It wasn't clear to me what prerequisite knowledge a reader should have, so some of these suggestions may not be needed.

Is there any chance you could turn on read-the-doc PR previews?

README.md

manics · 2023-03-02T18:05:05Z

README.md

@@ -2,41 +2,26 @@



Could be a good opportunity to add a badge?

[![continuous-integration](https://github.com/executablebooks/github-activity/actions/workflows/tests.yaml/badge.svg)](https://github.com/executablebooks/github-activity/actions/workflows/tests.yaml)

README.md

manics · 2023-03-02T18:13:08Z

README.md

-
-The easiest way to use `github-activity` to generate activity markdown is to use
-the command-line interface. It takes the following form:
+Use this tool via the command line like so:


It wasn't clear to me whether this is intended as a quick start in which case this should probably mention an auth token is needed, or if it's an example of how easy this is to use in which case it might be better to say After following the installation instructions you can use this tool via the command line like so: ?

docs/contribute.md

manics · 2023-03-02T18:22:37Z

docs/contribute.md

+2. **Draft a new release on GitHub**.
+   Under the [`releases` page](https://github.com/executablebooks/github-activity/releases) click [the `Draft a New Release` button](https://github.com/executablebooks/github-activity/releases/new).
+   - Connect the release to your release commit.
+   - Create a new tag for the release called `vM.m.p`.


I think vX.X.X as used above (or vX.Y.Z as used on https://semver.org/) is clearer than vM.m.p, it took me a while to realise it was just Major.minor.patch and not an abbreviation for something!

manics · 2023-03-02T18:29:28Z

docs/use.md

+  you don't need to set any scopes on the token you create.
+- When using `github-activity` from the command line, use the `--auth` parameter and pass
+  in your access token. This is easiest if you set it as an **environment variable**,
+  such as `MY_ACCESS_TOKEN`. You can then add it to your call like so:


From a security perspective, especially on a shared system, it's safer to set the GITHUB_ACCESS_TOKEN env-var instead of passing secrets on the command line

docs/use.md

manics · 2023-03-02T18:36:51Z

docs/use.md

+These sections describe how to control the major functionality of this tool.
+
+## Generate a markdown changelog
+


Is the expectation that a user should be able to follow this from top to bottom the first time they use this tool? If so I think mentioning the need for a GitHub token first would be helpful since it's mandatory

github-activity/github_activity/github_activity.py

Lines 159 to 168 in 1ce5486

if not auth:

raise ValueError(

"Either the environment variable GITHUB_ACCESS_TOKEN or the "

"--auth flag or must be used to pass a Personal Access Token "

"needed by the GitHub API. You can generate a token at "

"https://github.com/settings/tokens/new. Note that while "

"working with a public repository, you don’t need to set any "

"scopes on the token you create. Alternatively, you may log-in "

"via the GitHub CLI (`gh auth login`)."

)

docs/use.md

choldgraf · 2023-03-02T19:18:30Z

Interesting we haven't been building PRs even though it is checked on. I just cycled the check and also reopened this PR, let's see if that worked.

Will respond to comments tomorrow!

README.md

docs/contribute.md

Co-authored-by: Simon Li <orpheus+devel@gmail.com>

choldgraf · 2023-03-06T15:38:40Z

OK I made a few updates to the instructions here to make it easier to follow, thanks for the comments everybody!

I think this is good to go unless others would like to see more changes

choldgraf · 2023-03-06T15:56:09Z

Sorry that pre commit keeps breaking - the install fails on my machine right now because of a word glibc error

choldgraf · 2023-03-06T18:14:48Z

OK got the tests passing :-) I think this one is good to go from my end

choldgraf · 2023-11-14T22:12:40Z

Just realized we never actually merged this. @minrk in the future you should feel free to just merge rather than only hitting "approve"! :-)

Overhaul documentation and add contributing guide

86b3df3

choldgraf requested review from blink1073 and minrk March 1, 2023 15:38

blink1073 reviewed Mar 2, 2023

View reviewed changes

manics reviewed Mar 2, 2023

View reviewed changes

choldgraf closed this Mar 2, 2023

choldgraf reopened this Mar 2, 2023

choldgraf added 3 commits March 4, 2023 15:44

Prettier

5e6579b

Fix workflow

0b61e31

Ensure dirhtml exists

1630799

choldgraf commented Mar 6, 2023

View reviewed changes

README.md Show resolved Hide resolved

choldgraf commented Mar 6, 2023

View reviewed changes

docs/contribute.md Outdated Show resolved Hide resolved

choldgraf commented Mar 6, 2023

View reviewed changes

docs/contribute.md Outdated Show resolved Hide resolved

choldgraf and others added 2 commits March 6, 2023 07:25

Apply suggestions from code review

2733f75

Co-authored-by: Simon Li <orpheus+devel@gmail.com>

Clarify instructions after feedback

0f0cebe

blink1073 approved these changes Mar 6, 2023

View reviewed changes

minrk approved these changes Mar 13, 2023

View reviewed changes

choldgraf merged commit e64907c into main Nov 14, 2023

choldgraf deleted the publish-action branch November 14, 2023 22:12

consideRatio added the documentation Improvements or additions to documentation label Apr 10, 2025

		These sections describe how to control the major functionality of this tool.

		## Generate a markdown changelog

	if not auth:
	raise ValueError(
	"Either the environment variable GITHUB_ACCESS_TOKEN or the "
	"--auth flag or must be used to pass a Personal Access Token "
	"needed by the GitHub API. You can generate a token at "
	"https://github.com/settings/tokens/new. Note that while "
	"working with a public repository, you don’t need to set any "
	"scopes on the token you create. Alternatively, you may log-in "
	"via the GitHub CLI (`gh auth login`)."
	)

Conversation

choldgraf commented Mar 1, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blink1073 left a comment

Choose a reason for hiding this comment

Uh oh!

blink1073 Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

manics left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

manics Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

manics Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

manics Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

manics Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

manics Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

choldgraf commented Mar 2, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

choldgraf commented Mar 6, 2023

Uh oh!

choldgraf commented Mar 6, 2023

Uh oh!

choldgraf commented Mar 6, 2023

Uh oh!

choldgraf commented Nov 14, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

choldgraf commented Mar 1, 2023 •

edited

Loading