From 437d148f042dbda623af32b312d30b18df9097fd Mon Sep 17 00:00:00 2001 From: Oleh Dmytrychenko Date: Sun, 6 Nov 2022 16:08:34 +0200 Subject: [PATCH] Documentation housekeeping. Improved punctuation consistency. Fixed typo. Clarified PR section. --- CONTRIBUTING.md | 36 ++++++++++++++++++------------------ GITFLOW.rst | 3 +-- 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc30346..a332345 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,27 +35,27 @@ Developers with good ideas are encouraged to be bold and contribute code. ### Gitflow -Development of TKL is loosely based on [GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html), a widely accepted set of guidelines for contributing to projects over GitHub. As such, TKL development follows these basic guidelines: -* Anything in the master branch is deployable (builds that have successfully been proven to work) -* When working on something new (ie: a bugfix or a new feature), create a descriptively named branch off of the master. Each new branch should address a single issue. -* Commit to that branch locally and regularly. Source code should be documented and rational for changes included in commits. +Development of TKL is loosely based on [GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html), a widely accepted set of guidelines for contributing to projects over GitHub. As such, TKL development follows these basic guidelines: +* Anything in the master branch is deployable (builds that have successfully been proven to work). +* When working on something new (ie: a bugfix or a new feature), create a descriptively named branch off of the master. Each new branch should address a single issue. +* Commit to that branch locally and regularly. Source code should be documented and rationale for changes included in commits. * Open a pull request for help, feedback or branch merging. * Once someone else has reviewed and signed off on the changes, the project maintainer or a core developer will merge it with the official repository. -* Once it is merged and pushed to the master, the project should be rebuilt and released immediately. +* Once it is merged and pushed to the master, the project should be rebuilt and released immediately. -Collaboration is facilitated over GitHub through the use of [fork](https://help.github.com/articles/fork-a-repo/) and [pull requests](https://help.github.com/articles/using-pull-requests/).In order to make use of these features, developers will need to [create a GitHub account]() and add their SSH public key if they have not already done so. +Collaboration is facilitated over GitHub through the use of [fork](https://help.github.com/articles/fork-a-repo/) and [pull requests](https://help.github.com/articles/using-pull-requests/). In order to make use of these features, developers will need to [create a GitHub account]() and add their SSH public key if they have not already done so. ### Contribution Walkthrough **Fork and clone source:** * To begin, login and find a repository that you would like to work on. -* Within the desired repository, press the ``fork`` button to fork the repository. +* Within the desired repository, press the ``fork`` button to fork the repository. * The repository will then need to be cloned before you can work on it. You can do so with this snippet of code: `git clone git@github.com:USERNAME/PROJECTNAME.git` * Once the repository has been cloned, it will have a ``remote`` called ``origin``. This will point to your newly created fork on GitHub rather than the original repository. -*You will need to add another ``remote`` in order to keep track of the original repository. In this example, it will be called ``upstream``: +* You will need to add another ``remote`` in order to keep track of the original repository. In this example, it will be called ``upstream``: ``` cd PROJECTNAME @@ -79,27 +79,27 @@ git merge upstream/master Now that you're finished and all changes are committed, you need to push them to your GitHub repository: - `git push origin DESCRIPTIVE_BRANCH_NAME` + git push origin DESCRIPTIVE_BRANCH_NAME -Finally, submit a ``pull request``so that the maintainer or a core developer may review your changes and merge them into the official repository.If for some reason the maintainer or one of the core developers has a problem with your change, they won't want to merge until fixed. However, whenever you commit and push more changes to that branch of your code, they will be included in that original pull request until it is closed. +Finally, submit a ``pull request`` so that the maintainer or a core developer may review your changes and provide necessary feedback. Further commits pushed into the same branch will be automatically included in your ``pull request`` until it is closed. Upon successfull review your changes will be merged into the official repository. ### Bug Reports and feature requests -TKL uses GitHub's project management features to track development. Included in these features are the [issue tracker](https://github.com/turnkeylinux/tracker/issues/) (used to report bugs and record feature requests) and the [Wiki](https://github.com/turnkeylinux/tracker/wiki) (used to propose and track appliance candidates and as a general purpose whiteboard for TKL development). +TKL uses GitHub's project management features to track development. Included in these features are the [issue tracker](https://github.com/turnkeylinux/tracker/issues/) (used to report bugs and record feature requests) and the [Wiki](https://github.com/turnkeylinux/tracker/wiki) (used to propose and track appliance candidates and as a general purpose whiteboard for TKL development). Before opening a new issue, please check to see if a similar bug, issue or feature request already exists in the tracker. If a similar topic is currently open, post a comment stating that it also affects you. Knowing an issue affects multiple users is useful when we decide how to prioritize limited development resources. Please try and include any additional information you think might help us close the issue. The ideal bug / issue report includes: -* A detailed description of the bug / issue -* Step by step instructions on how it may be reproduced -* the output that is generated from using the ``turnkey-version`` command, which should look like this: +* A detailed description of the bug / issue. +* Step by step instructions on how it may be reproduced. +* The output that is generated from using the ``turnkey-version`` command, which should look like this: ``` turnkey-appliance_name-major_version.minor_version-debian_codename-architecture ``` The ideal feature request includes: -* A detailed description of the feature and the component it relates to -* One or more cases in which the feature might be of use -* Any other relevant information +* A detailed description of the feature and the component it relates to. +* One or more cases in which the feature might be of use. +* Any other relevant information. -Note that the tracker is not intended to for use as a forum for support or general discussion. For technical support or general discussion, please use the appropriate [forum](https://www.turnkeylinux.org/forum). +Note that the tracker is not intended to be used as a forum for support or general discussion. For technical support or general discussion, please use the appropriate [forum](https://www.turnkeylinux.org/forum). diff --git a/GITFLOW.rst b/GITFLOW.rst index 34b8b1f..3161a7b 100644 --- a/GITFLOW.rst +++ b/GITFLOW.rst @@ -28,7 +28,7 @@ follows these guidelines: should address just one issue (i.e. create a separate branch from master for each issue). * Commit to that branch locally and regularly. Source code should be - documented and rational for changes included in commits. + documented and rationale for changes included in commits. * When you need feedback or help, or you think the branch is ready for merging, open a pull request. * After someone else has reviewed and signed off on the changes, the @@ -125,4 +125,3 @@ until it is closed. .. _git-flow: http://nvie.com/posts/a-successful-git-branching-model .. _GitHub flow: http://scottchacon.com/2011/08/31/github-flow.html .. _GitHub account: https://github.com/signup -