social-docs icon indicating copy to clipboard operation
social-docs copied to clipboard

adapt CONTRIBUTING.md for python-social-auth/social-docs

Open das-g opened this issue 8 years ago • 0 comments

It seems this repository (python-social-auth/social-docs) just has the same CONTRIBUTING.md as the other python-social-auth/* repos. But some of the stuff in there makes little or no sense for a pure documentation repository in general or sometimes makes little or no sense for this specific repository.

How to contribute

I like to encourage you to contribute to the repository.

This should be as easy as possible for you but there are a few things to consider when contributing. The following guidelines for contribution should be followed if you want to submit a pull request.

How to prepare

:white_check_mark: Well, that's a given. Let's leave that in.

  • Submit an issue ticket for your issue if there is no one yet.
    • Describe the issue and include steps to reproduce if it's a bug.
    • Ensure to mention the earliest version that you know is affected.

:thinking: Does this make sense for documentation? Issue tickets might be warranted for documentation changes that need some discussion first, or that the one who brings up the issue can't or doesn't want to fix themselves. Otherwise, I'd say a PR should suffice.

:red_circle: For documentation bugs "steps to reproduce" will only sometimes be meaningful, I think.

  • If you are able and want to fix this, fork the repository on GitHub

:white_check_mark: Sounds good.

Make Changes

  • In your forked repository, create a topic branch for your upcoming patch. (e.g. feature/new-backend or bug/auth-fails)
    • Usually this is based on the master branch.
    • Create a branch based on master git branch bug/auth-fails master then checkout the new branch with git checkout bug/auth-fails. Please avoid working directly on the master branch.

:neutral_face: While this makes sense per-se, unfortunately GitHub doesn't allow users to choose meaningful branch names when they don't clone the repo to their local machine and don't explicitly fork the repo on GitHub first and only then edit a file online in their fork: If one attempts to edit a file on the original repo (without having write access) GitHub will implicitly fork it and automatically create a branch named patch-1 (or some other number if there already was a fork and that branch name was already taken).

  • Make commits of logical units and describe them properly.

:white_check_mark: Makes sense if "of logical units" refers to a somewhat atomic set of changes. (The changes themselves could be distributed over several units of the repo if they need to be made together to make sense.)

  • Make sure you stick to PEP8 coding style that is used already.

:thinking: Is this about code examples in the documentation? Otherwise it doesn't make much sense in a repo mainly consisting of MarkDown, HTML and CSS files.

  • If possible, submit tests to your patch / new feature so it can be tested easily.
  • Assure nothing is broken by running all the tests.

:red_circle: As far as I can see, this repo contains no tests.

  • Add a meaningful entry to the CHANGELOG.md document.

:thinking: Maybe this should be limited to notable changes. Documentation repositories are bound to get lots of contributions that just fix typos, grammar, etc.

[...]

das-g avatar Apr 27 '17 13:04 das-g