diff options
| -rw-r--r-- | CONTRIBUTING.md | 83 | ||||
| -rw-r--r-- | README.md | 1 |
2 files changed, 27 insertions, 57 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f46087c06..f414ef5b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,32 +36,27 @@ Create a [gpg key](http://www.gossamer-threads.com/lists/gentoo/dev/268496?do=po Now git will sign your commits to the overlay by using the gpg key. -* **Install [hub](http://hub.github.com/)**, the *command-line wrapper for git that makes you better at GitHub*. +* **Install [pkgdev](https://github.com/pkgcore/pkgdev)**, *A repository commit helper* -*hub* can be used equivalent to to *git* and upstream even recommends *"alias git='hub'*. +*pkgdev* sanitizes your commit in a convenient way and runs QA checks. - emerge dev-vcs/hub - -* **Install [repo-commit](https://bitbucket.org/gentoo/repo-commit/)**, *A repository commit helper* - -*repo-commit* sanitizes your commit in a convenient way. - - emerge app-portage/repo-commit + emerge dev-util/pkgdev --- ## Contributing ebuilds +### Fork the overlay +In order to send pull request and ask for inclusion of your changes you need to have your own fork of the overlay on github. You can do this by clicking the "Fork" button in the top right of our GitHub page. + ### Clone the overlay -Create a local checkout of the overlay +Create a local checkout of your fork, where `USERNAME` is your GitHub username. - hub clone gentoo-science/sci + git clone git@github.com:USERNAME/sci.git -### Fork the overlay -In order to send pull request and ask for inclusion of your changes you need to have your own fork of the overlay on github. You can do this by issuing +To conveniently update your fork later, add the main repository as a second remote - cd sci - hub fork + git remote add upstream git@github.com:gentoo/sci.git ### Branch out for contribution It is always convenient for development as well as for the review and merging process, if the development is done in branches. Let's branch the overlay into a local branch named PACKAGE_NAME. @@ -71,37 +66,38 @@ It is always convenient for development as well as for the review and merging pr For the fastest process during merging it is best to have a single branch per package. ### Work on the package -Now you are ready to work on your package of interest. Once you are finished you should _always_ use **[repoman](http://dev.gentoo.org/~zmedico/portage/doc/man/repoman.1.html)** to do a static analysis of your work. +Now you are ready to work on your package of interest. Once you are finished you should _always_ use **[pkgcheck](https://pkgcore.github.io/pkgcheck/man/pkgcheck.html)** to do a static analysis of your work. This can be done with - repoman full + pkgcheck scan --net ### Commit your work Once *all* reported problems are resolved, you can commit it - repo-commit "Here we write a comprehensible commit message" + pkgdev commit --all -### Push to Github and make a pull request +### Push to GitHub and make a pull request In order to facilitate potential reverts of mistakes, we prefer to keep the git history as linear as possible. For this, always rebase your changes on the latest remote changes. - hub pull --rebase=preserve github master + git pull --rebase=merges upstream master + +Next we push back the changes in the PACKAGE_NAME branch to our fork. -Next we push back the changes in the PACKAGE_NAME branch to our fork and send a pull-request to the overlay maintainers. + pkgdev push YOUR_GITHUB_USER PACKAGE_NAME - hub push YOUR_GITHUB_USER PACKAGE_NAME - hub pull-request +Now we are ready to create a Pull Request, go to your GitHub fork and press "Contribute" --> "Open pull request". -Lastly you need to wait for review comments and the merge of your work. If you feel that they are slacking, don't bother to ping them again. In case you need to include some improvements, just commit your work again using *repo-commit* and push it again to your fork. No need to send another pull-request as your new changes will be added to the original one. +Lastly you need to wait for review comments and the merge of your work. If you feel that they are slacking, don't hesitate to ping them again. In case you need to include some improvements, just commit your work again using `pkgdev commit` and push it again to your fork. No need to send another pull-request as your new changes will be added to the original one. ### What's next? -If you would like to get direct access to the overlay, prove some contribution and ping us via sci@gentoo.org or on irc in #gentoo-science @ freenode. If you would like to become a dev yourself, prove some more contributions and again, contact us. We are always looking for new candidates. +If you would like to get direct access to the overlay, prove some contribution and ping us via sci@gentoo.org or on irc in #gentoo-science @ Libera. If you would like to become a dev yourself, prove some more contributions and again, contact us. We are always looking for new candidates. ---- ## Ebuild recommendations As the Gentoo Science overlay is a constant work-in-progress, we have some recommendations for prospective contributors: -* **Aim for writing EAPI=7 ebuilds.** For certain eclasses, EAPI=7 is not allowed yet. In such cases you may use EAPI=6. We will not accept EAPI<6 ebuilds. +* **Aim for writing EAPI=8 ebuilds.** For certain eclasses, `EAPI=8` is not allowed yet. In such cases you may use `EAPI=7`. We will not accept `EAPI<=6` ebuilds. * **Version bumps should always follow the latest guidelines.** For instance, a version bump of an ebuild that still employs autotools-utils.eclass should be avoided. Instead, drop 'autotools-utils', move to 'autotools' and call `default` followed by `eautoreconf` in src_prepare(). ---- @@ -109,46 +105,21 @@ As the Gentoo Science overlay is a constant work-in-progress, we have some recom **It is important, that if you merge a pull request, you should feel as responsible as if you have written the commits yourself!** - - ### Prerequisite -Make sure you have both repos (github & gentoo.org) as remotes defined. - - git remote -v - -should give - ->github git@github.com:gentoo-science/sci.git (fetch) -> ->github git@github.com:gentoo-science/sci.git (push) -> ->origin git+ssh://git@git.overlays.gentoo.org/proj/sci.git (fetch) -> ->origin git+ssh://git@git.overlays.gentoo.org/proj/sci.git (push) - +Install `app-portage/pram` ### Review process -In the beginning you should review the pull request on github directly and recommend as much improvements as possible. By this you train the new contributor towards becoming a new dev, which should be our final goal. +In the beginning you should review the pull request on GitHub directly and recommend as much improvements as possible. By this you train the new contributor towards becoming a new dev, which should be our final goal. #### Checking out the pull-request as local branch Once everything is fine or you like to fix the rest yourself, simply use the following command to get the pull-request in a new branch in your repo. - hub checkout https://github.com/gentoo-science/sci/pull/PULLREQUEST-NUMBER - -#### Testing and repoman check -Now check the package by building and installing it, and run *repoman* in the package dir. Remember, when merging a pull request you take the responsibility for the quality of the commit. - -#### Merge the pull-request branch into master -If this is also fine, merge the branch into the master - - git checkout master - git merge USER-BRANCH - -#### Merging the two remote HEADs -Finally use the script **merge-dualHEAD** from the *scripts* directory to merge the github and gentoo.org remote repo. + pram -r gentoo/sci PULLREQUEST-NUMBER +#### Testing and pkgcheck check +Now check the package by building and installing it, and run *pkgcheck* in the package directory. Remember, when merging a pull request you take the responsibility for the quality of the commit. --- #### Contribution to the document @@ -1,6 +1,5 @@ # The [Gentoo Science Project](https://wiki.gentoo.org/wiki/Project:Science) Repository [](https://github.com/gentoo/sci/actions?query=workflow%3Apkgcheck) -[](https://github.com/gentoo/sci/actions?query=workflow%3Arepoman) [](https://github.com/gentoo/sci#guide) [](https://web.libera.chat/#gentoo-science) |