Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
das-g opened this issue Apr 27, 2017 · 0 comments
Open

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

das-g opened this issue Apr 27, 2017 · 0 comments

Comments

@das-g
Copy link
Contributor

das-g commented Apr 27, 2017

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

✅ 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.

🤔 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.

🔴 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

✅ 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.

😐 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.

✅ 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.

🤔 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.

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

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

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

[...]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

No branches or pull requests

1 participant