|
| 1 | +Contributing guide |
| 2 | +================== |
| 3 | + |
| 4 | +Thanks for your interest in contributing to cpplint. |
| 5 | + |
| 6 | +Any kinds of contributions are welcome: Bug reports, Documentation, Patches. |
| 7 | + |
| 8 | +However cpplint is a bit special as a project because it aims to closely follow what Google does in the upstream repository. |
| 9 | +That means Google remains the source of all major requirements and functinoality of cpplint, where as this fork adds extensions to cpplint run on more environments and in more companies. |
| 10 | +The difference between this cpplint and Google should remain so small that anyone can at a glance see there is no added change that could be regarded as a security vulnerability. |
| 11 | + |
| 12 | +Here are some tips to make best use of your time: |
| 13 | + |
| 14 | +1. Feature suggestions should initially be opened at the `upstream repository <https://github.com/google/styleguide>`_, but feel free to open an issue here to and link to the upstream issue. |
| 15 | + |
| 16 | +2. Consider the goals and non-goals of this project: |
| 17 | + |
| 18 | +Goals: |
| 19 | + |
| 20 | +* Provides cpplint as a PyPI package for multiple python versions |
| 21 | +* Add a few features and fixes aimed at usages outside Google |
| 22 | + |
| 23 | +Non-Goals: |
| 24 | + |
| 25 | +* Become an independent fork adding major features |
| 26 | +* Fix python style issues in cpplint |
| 27 | + |
| 28 | + |
| 29 | +Development |
| 30 | +----------- |
| 31 | + |
| 32 | +For many tasks, it is okay to just develop using a single installed python version. But if you need to test/debug the project in multiple python versions, you need to install those version:: |
| 33 | + |
| 34 | +1. (Optional) Install multiple python versions |
| 35 | + |
| 36 | + 1. (Optional) Install [pyenv](https://github.com/pyenv/pyenv-installer) to manage python versions |
| 37 | + 2. (Optional) Using pyenv, install the python versions used in testing:: |
| 38 | + |
| 39 | + pyenv install 2.7.16 |
| 40 | + pyenv install 3.6.8 |
| 41 | + |
| 42 | +It may be okay to run and test python against locally installed libraries, but if you need to have a consistent build, it is recommended to manage your environment using virtualenv: [virtualenv](https://virtualenv.pypa.io/en/latest/ ), [virtualenvwrapper](https://pypi.org/project/virtualenvwrapper/ ): |
| 43 | + |
| 44 | +1. (Optional) Setup a local virtual environment with all necessary tools and libraries:: |
| 45 | + |
| 46 | + mkvirtualenv cpplint [-p /usr/bin/python3] |
| 47 | + pip install .[dev] |
| 48 | + |
| 49 | +Alternatively you can locally install patches like this:: |
| 50 | + |
| 51 | + pip install --user -e .[dev] |
| 52 | + |
| 53 | +You can setup your local environment for developing patches for cpplint like this: |
| 54 | + |
| 55 | +.. code-block:: bash |
| 56 | +
|
| 57 | + # run a single test |
| 58 | + pytest cpplint_unittest.py -k testExclude |
| 59 | + # run all tests |
| 60 | + ./setup.py test |
| 61 | + ./setup.py lint |
| 62 | + ./setup.py style |
| 63 | + ./setup.py ci # all the above |
| 64 | + ./tox # all of the above in all python environments |
| 65 | +
|
| 66 | +Releasing |
| 67 | +--------- |
| 68 | + |
| 69 | +To release a new version: |
| 70 | + |
| 71 | +.. code-block:: bash |
| 72 | +
|
| 73 | + # prepare files for release |
| 74 | + vi cpplint.py # increment the version |
| 75 | + vi changelog.rst # log changes |
| 76 | + git commit -m "Releasing x.y.z" |
| 77 | + git add cpplint.py changelog.rst |
| 78 | + # test-release (on env by mkvirtualenv -p /usr/bin/python3) |
| 79 | + pip install --upgrade setuptools wheel twine |
| 80 | + python3 setup.py sdist bdist_wheel |
| 81 | + twine upload --repository testpypi dist/* |
| 82 | + # ... Check website and downloads from https://test.pypi.org/project/cpplint/ |
| 83 | + # Actual release |
| 84 | + twine upload dist/* |
| 85 | + git tag x.y.z |
| 86 | + git push |
| 87 | + git push --tags |
| 88 | +
|
| 89 | +
|
| 90 | +Catching up with Upstream |
| 91 | +------------------------- |
| 92 | + |
| 93 | +For maintainers, it is a regular duty to look at what cpplint changes were merged upstream, to include them in this fork. |
| 94 | + |
| 95 | +Checkout here and upstream google: |
| 96 | + |
| 97 | +.. code-block:: bash |
| 98 | +
|
| 99 | + git clone git@github.com:cpplint/cpplint.git |
| 100 | + cd cpplint |
| 101 | + git remote add google https://github.com/google/styleguide |
| 102 | +
|
| 103 | +To incorporate google's changes: |
| 104 | + |
| 105 | +.. code-block:: bash |
| 106 | +
|
| 107 | + git fetch google gh-pages |
| 108 | + git checkout -b updates FETCH_HEAD |
| 109 | + git rebase master # this will have a lot of conflicts, most of which can be solved with the next command (run repeatedly) |
| 110 | + # solve conflicts with files deleted in our fork (this is idempotent and safe to be called. when cpplint.py has conflicts, it will do nothing) |
| 111 | + git status | grep 'new file:' | awk '{print $3}' | xargs -r git rm --cached ; git status | grep 'deleted by us' | awk '{print $4}' | xargs -r git rm ; git status --untracked-files=no | grep 'nothing to commit' && git rebase --skip |
| 112 | +
|
| 113 | + git push -u origin updates |
| 114 | + # check travis |
| 115 | + git push origin --delete updates |
| 116 | +
|
| 117 | + git rebase updates master |
| 118 | + git branch -D updates |
| 119 | + git push |
| 120 | +
|
| 121 | +Setup fetching of pull requests in .git/config: |
| 122 | + |
| 123 | +.. code-block:: bash |
| 124 | +
|
| 125 | + [remote "origin"] |
| 126 | + url = git@github.com:cpplint/cpplint.git |
| 127 | + fetch = +refs/heads/*:refs/remotes/origin/* |
| 128 | + # following line should be new, fetches PRs from cpplint |
| 129 | + fetch = +refs/pull/*/head:refs/remotes/origin/pr/* |
| 130 | + [remote "google"] |
| 131 | + url = https://github.com/google/styleguide |
| 132 | + fetch = +refs/heads/*:refs/remotes/google/* |
| 133 | + # following line should be new, fetches PRs from google/styleguides |
| 134 | + fetch = +refs/pull/*/head:refs/remotes/google/pr/* |
| 135 | +
|
| 136 | +
|
| 137 | +To compare this for with upstream (after git fetch): |
| 138 | + |
| 139 | +.. code-block:: bash |
| 140 | +
|
| 141 | + git diff google/gh-pages:cpplint/cpplint.py master:cpplint.py |
| 142 | + git diff google/gh-pages:cpplint/cpplint_unittest.py master:cpplint_unittest.py |
0 commit comments