From f6954b29b08fcbc54e252c262d949de0073a92f9 Mon Sep 17 00:00:00 2001 From: Peter Harrison Date: Sun, 6 Sep 2020 21:10:52 -0700 Subject: [PATCH] Fixes: #5 --- CONTRIBUTORS.rst | 10 ++++ docs/contributing.rst | 110 ++++++++++++++---------------------------- docs/index.rst | 3 +- docs/installation.rst | 4 +- docs/maintainers.rst | 57 ++++++++++++++++++++++ 5 files changed, 108 insertions(+), 76 deletions(-) create mode 100644 CONTRIBUTORS.rst create mode 100644 docs/maintainers.rst diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst new file mode 100644 index 0000000..c330c94 --- /dev/null +++ b/CONTRIBUTORS.rst @@ -0,0 +1,10 @@ +Contributions to the project +============================ + +In chronological order: + +* Peter Harrison + * Creator of original code + +* [Your name or handle] <[email or website]> + * [Brief summary of your changes] diff --git a/docs/contributing.rst b/docs/contributing.rst index d0d8c14..3ab1dfe 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -6,16 +6,16 @@ Start contributing today! Introduction ------------ -Below is the workflow for having your contribution accepted into the ``pattoo-agent-bacnet`` repository. +Below is the workflow for having your contribution accepted into the ``pattoo`` repository. -#. Create an Issue or comment on an existing issue to discuss the feature -#. If the feature is approved, assign the issue to yourself -#. Fork the project -#. Clone the fork to your local machine -#. Add the original project as a remote (git remote add upstream https://github.com/PalisadoesFoundation/pattoo-agent-bacnet, check with: git remote -v) -#. Create a topic branch for your change (git checkout -b ``BranchName``\ ) -#. you may create additional branches if modifying multiple parts of the code -#. Write code and Commit your changes locally. An example of a proper ``git commit`` message can be seen below: +#. `Check for open issues or open a fresh issue to start a discussion `_ around a feature idea or a bug. There is a `good first issue` tag for issues that should be ideal for people who are not very familiar with the codebase yet + * Assign an interesting existing issue to yourself. + * If you created a discussion issue for a new feature or bugfix, then make sure it's `approved by a maintainer `_ before assigning the issue to yourself. +#. `Fork the repository on GitHub `_ in preparation for your changes +#. Clone your GitHub repository to your local machine +#. Add the original project as a remote repository `git remote add upstream https://github.com/PalisadoesFoundation/pattoo-agent-bacnet`. Check everything is OK with `git remote -v`. +#. Create a branch named after your issue like this using `git checkout -b issue-789` where `789` is the number of your issue. +#. Write code modifying this branch and commit your changes locally. An example of a proper git commit` message can be seen below: .. code-block:: text @@ -34,32 +34,49 @@ Below is the workflow for having your contribution accepted into the ``pattoo-ag Resolves Issue: #123 See also: #456, #789 -#. When you need to synch with upstream (pull the latest changes from main repo into your current branch), do: +#. We periodically update the master branch of our code. To synchronize the latest changes from our main repository into your current branch do: - #. ``git fetch upstream`` - #. ``git merge upstream/master`` + .. code-block:: text + + git fetch upstream + git merge upstream/master -#. Check for unnecessary white space with ``git diff --check``. +#. Read the documentation on how to `setup and run tests. `_ #. Write the necessary unit tests for your changes. #. Run all the tests to assure nothing else was accidentally broken -#. Push your changes to your forked repository (git push origin ``branch``\ ) -#. Perform a pull request on GitHub -#. Your code will be reviewed -#. If your code passes review, your pull request will be accepted +#. Push your changes to your forked repository: + + .. code-block:: text + + git push origin issue-789 + +#. Perform a pull request on GitHub. +#. `Bug the maintainer `_ until it gets accepted and merged. :) +#. Make sure to add yourself to `CONTRIBUTORS.rst `_ Code Style Guide ---------------- For ease of readability and maintainability code for all ``pattoo`` projects must follow these guidelines. Code that does not comply will not be added to the ``master`` branch. -#. All ``pattoo`` projects use the `Google Python Style Guide `_ for general style requirements +#. All ``pattoo`` python projects use the `Google Python Style Guide `_ for general style requirements #. All ``pattoo`` python projects use the The Chromium Projects Python Style Guidelines for docstrings. #. Indentations must be multiples of 4 blank spaces. No tabs. -#. All strings must be enclosed in single quotes +#. All strings must be enclosed in single quotes. +#. All code must be compliant with: + +.. code-block:: text + + pylint + PEP8 + PEP257 + pydocstyle + pycodestyle + #. In addition too being ``pylint`` compliant, the code must be PEP8 and PEP257 compliant too. #. There should be no trailing spaces in files -Guidelines to remember +Guidelines to Remember ^^^^^^^^^^^^^^^^^^^^^^ * Always opt for the most pythonic solution to a problem @@ -77,56 +94,3 @@ The ``pattoo`` projects strive to maintain a proper log of development through w #. https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message #. http://chris.beams.io/posts/git-commit/ - -Sample .vimrc File for Compliance -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can use this sample .vimrc file to help meet our style requirements - -.. code-block:: vim - - " Activate syntax - syntax on - " set number - - " Disable automatic comment insertion - autocmd FileType * setlocal formatoptions-=c formatoptions-=r formatoptions-=o - - " Delete trailing whitespace - autocmd BufWritePre * :%s/\s\+$//e - - " Convert tabs to spaces - set expandtab - - " Set tabs to 4 spaces - set tabstop=4 - - " Set the number of spaces for indentation - set shiftwidth=4 - - " Switch on highlighting the last used search pattern when the terminal has colors - if &t_Co > 2 || has("gui_running") - set hlsearch - endif - - " Tell vim to remember certain things when we exit - " '10 : marks will be remembered for up to 10 previously edited files - " "100 : will save up to 100 lines for each register - " :20 : up to 20 lines of command-line history will be remembered - " % : saves and restores the buffer list - " n... : where to save the viminfo files - set viminfo='10,\"100,:20,%,n~/.viminfo - - " Function for viminfo to work - function! ResCur() - if line("'\"") <= line("$") - normal! g`" - return 1 - endif - endfunction - - " Function for viminfo to work - augroup resCur - autocmd! - autocmd BufWinEnter * call ResCur() - augroup END diff --git a/docs/index.rst b/docs/index.rst index c96bea4..05b8db5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,7 @@ Pattoo Agents ``pattoo`` agents collect IoT data for a centralized ``pattoo`` server. -Visit the `Pattoo Agents GitHub site `_ to see the code. +Visit the `Pattoo Agents GitHub site `_ to see the code. Introduction ------------ @@ -59,3 +59,4 @@ Developers :caption: Developers: contributing + maintainers diff --git a/docs/installation.rst b/docs/installation.rst index 411bc2d..339f2a7 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -25,14 +25,14 @@ Follow these steps. $ mkdir -p /installation/parent/directory $ cd /installation/parent/directory -#. Clone the repository to the parent directory using the ``git clone`` command. You can also choose to downloading and unzip the file in the parent directory. The repository can be found at: https://github.com/PalisadoesFoundation/pattoo-agent-bacnet. +#. Clone the repository to the parent directory using the ``git clone`` command. You can also choose to downloading and unzip the file in the parent directory. The repository can be found at: https://github.com/PalisadoesFoundation/pattoo-agent-bacnet-agent-bacnet. **Note** The repository should not be cloned to a directory with ``/home`` in its path .. code-block:: bash $ cd /installation/parent/directory - $ git clone https://github.com/PalisadoesFoundation/pattoo-agent-bacnet.git + $ git clone https://github.com/PalisadoesFoundation/pattoo-agent-bacnet-agent-bacnet.git 4. Enter the ``/installation/parent/directory/pattoo-agent-bacnet`` directory with the ``pattoo-agent-bacnet`` files. #. Install the below packages from the ``pip_requirements`` document in the ``pattoo-agent-bacnet`` root directory for a seamless installation using the diff --git a/docs/maintainers.rst b/docs/maintainers.rst new file mode 100644 index 0000000..cb86b84 --- /dev/null +++ b/docs/maintainers.rst @@ -0,0 +1,57 @@ +Maintainers +=========== + +We are a community maintained project. Contributions can only +be approved and merged by the maintainers listed below. + +Maintainers +----------- + +Peter Harrison + :GitHub: `palisadoes `_ + :Website: `simiya `_ + +Shannika Jackson + :GitHub: `bonnie-23 `_ + +Dominic Henry + :GitHub: `Dev-Dominic `_ + +Cargill Seiveright + :GitHub: `gill876 `_ + +Jason Gayle + :GitHub: `DangaRanga `_ + +Maintainer Guidelines +--------------------- + +Our maintainers follow these guidelines. + +Communication +............. + +Maintainers use the thepalisadoes-dyb6419.slack.com slack channel for communication. + +Maintainer Contributions +........................ + +Maintainers can merge code into the various branches. + +#. This brings great responsibility and visibility. If your code, or code you approve, fails then everyone will know and will be able to revert to a previous pull request. Reviews must be thorough and must follow `Google's best practices. `_ This includes: + - The code is well-designed. + - The functionality is good for the users of the code. + - Any UI changes are sensible and look good. + - Any parallel programming is done safely. + - The code isn’t more complex than it needs to be. + - The developer isn’t implementing things they might need in the future but don’t know they need now. + - Code has appropriate unit tests. + - Tests are well-designed. + - The developer used clear names for everything. + - Comments are clear and useful, and mostly explain why instead of what. + - Code is appropriately documented (generally in g3doc). + - The code conforms to our style guides. +#. A maintainer's modifications to the code base must be reviewed and merged by another maintainer. Maintainers have been selected for their coding ability. They must therefore comply with `Google's best practices. `_. Because of this, the degree of review can be less exacting, and focus on: + - Readability + - Code style + - Obvious flaws in the workflow