Mercurial > vanilla
changeset 31:afb6f8eb89da
vanilla: add more documentation
author | David Demelier <markand@malikania.fr> |
---|---|
date | Tue, 26 Feb 2019 09:16:42 +0100 |
parents | 345ba1fec137 |
children | f0e059497bfa |
files | CONTRIBUTE.md README.rc.md README.templates.md STYLE.md templates/rc templates/rc.template |
diffstat | 6 files changed, 518 insertions(+), 68 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/CONTRIBUTE.md Tue Feb 26 09:16:42 2019 +0100 @@ -0,0 +1,242 @@ +vanilla CONTRIBUTING GUIDE +========================== + +Read this guide if you want to contribute to vanilla. The purpose of this +document is to describe the steps to submit a patch. + +You may submit a patch when: + +- You want to fix a bug / typo, +- You want to add a new feature, +- You want to change something. + +There a lot of steps before submitting a patch. First, be sure to respect the +style defined in the STYLE.md file. We never accept patches that do not match +the rules. + +Subscribe to the mailing list +----------------------------- + +Discussion and patches are sent to the *vanilla-dev@malikania.fr* mailing list. +You need to subscribe by dropping a mail to +*vanilla-dev+subscribe@malikania.fr* first. + +Enable patchbomb extension +-------------------------- + +While this step is optional, it brings the `hg email` command which makes most +of your submission for you. + +To enable it, add the following into your .hgrc (you may also use the hgrc file +from the repository in .hg/hgrc). + + [extensions] + patchbomb = + +Then, you need to specify a mail server, if you want to use smtp, you can use +something like this: + + [email] + from = Your Name <youraddress@yourdomain.tld> + to = vanilla@malikania.fr + + [smtp] + host = yourdomain.tld + port = 587 + tls = starttls + username = your_account + password = your_password + +Note: the password is optional, if not set it will be asked each time you run +the `hg email command`. + +More options are available, see: + +- `hg help hgrc.email`, +- `hg help hgrc.smtp`, +- `hg help patchbomb` +- `hg help email` + +### Note to GMail users + +By default, your GMail account may use 2-steps authentication which causes +troubles with the `hg email` command, you must create a specific application +password. + +1. Go to https://security.google.com/settings/security/apppasswords +2. Create an application password, it will be auto generated, +3. Use this password or store it directly in the `smtp.password` option. + +Use the following settings: + + [smtp] + host = gmail.com + port = 587 + tls = starttls + username = your_account@gmail.com + password = the_generated_application_password + +Create your patch +----------------- + +Usually, when you create a patch, you should have your own copy of vanilla +in your directory. + +The following steps assumes that you have already cloned the vanilla +repository somewhere. + +Note: the recommended way is to create one unique revision. + +### Commit messages + +Commit messages are written using the following syntax: + + topic: short message less than 80 characters + + Optional additional description if needed. + +Replace `topic` with one of the following: + +- **vanilla**: for a non package changeset, +- **category/package**: for a specific package. + +### Quick way + +If you plan to create a very small patch that consists of several lines, you can +use the following way by disabling the @ bookmark to avoid moving it. + + $ hg pull # fetch last changesets + $ hg up @ # update to the last revision + $ hg book -i @ # disable the @ bookmark (optional but recommended) + (edit some files) + $ hg commit # create a unique revision + $ hg email -r . # send a mail about the current revision (interactive) + +### Bookmark way + +We use Mercurial bookmarks as our workflow but we do share only @ bookmark +except when a long feature is being developed in parallel. Otherwise bookmarks +stay locally most of the time. + +When you start working on a new feature, you **must** always start from the @ +bookmark. + +You can use this workflow if you plan to create a patch that consists of +multiple revisions. + +Example: + + $ hg pull + $ hg up @ + $ hg book feature-xyz + (work) + $ hg commit + (work) + $ hg commit + $ hg email -r first:last + +Here, you must specify **first** and **last** as the initial and last revisions +respectively. You can check these revisions using `hg log` (also try `hg log -G` +or the nice TortoiseHg interface). + +Example, I've started to work on an a feature named **feature-xyz**, the log +looks like this: + + changeset: 22:3fb15d8fc454 + bookmark: feature-xyz + tag: tip + user: François Jean <fj@gmail.com> + date: Thu Dec 08 16:08:40 2016 +0100 + summary: vanilla: some other changes + + changeset: 21:f27e577c5504 + user: François Jean <fj@gmail.com> + date: Thu Dec 08 16:03:06 2016 +0100 + summary: vanilla: some changes + + changeset: 20:777023816ff9 + bookmark: @ + user: David Demelier <markand@malikania.fr> + date: Thu Dec 08 16:02:26 2016 +0100 + summary: vanilla: fix a bug + +The two revisions I want to export are 21 and 22, so I use `hg email -r 21:22`, +once done, see the section below. + +Additional topics +----------------- + +### Your patch is accepted + +The safest choice is to just pull from the central repository and update to the +@ bookmark. + + $ hg pull + $ hg up @ + +You can also call `hg rebase` (from rebase extension) to move your revisions on +top of upstream. If the patches were incorporated verbatim, they will be safely +discarded automatically. + + $ hg pull + $ hg up @ + $ hg rebase -b feature-xyz -d @ + $ hg book -d feature-xyz + +If you didn't created a bookmark replace **feature-xyz** with your revision +number. + +Finally, if you prefer to remove the revisions you have created, use `hg strip` +like explained in the see section below. + +### Your patch is discarded + +For some reasons, your patch can not be integrated within the official +repository, you can remove the revisions you have commited or keep them. + +If you want to remove the revisions, you can use the `hg strip` command (from +the strip extension). + +Warning: it will **remove** the revisions from history so use with care. + + $ hg strip -r 21:22 # using the example above + $ hg book -d feature-xyz # delete the bookmark + +Newer versions of Mercurial support `-B` argument: + + $ hg strip -B feature-xyz # shortcut + +You can just go back on the @ bookmark as it's the safest choice. + + $ hg pull # fetch changesets + $ hg up @ # update to @ + +### How to merge upstream code to continue my patch + +Sometimes when you started working on a topic, you may need to pull changes from +the repository. The idea is to pull the changes and rebase your work on top of +it. + +You must run these commands while your bookmark is active + + $ hg up feature-xyz + $ hg pull -B @ + $ hg rebase -b feature-xyz -d @ + +### I forgot to create a bookmark and accidentally moved the @ bookmark + +If you forgot to create a custom bookmark or disable @ before committing, you +may have moved the @ bookmark in your repository. The `hg pull` command can +recover it. + +First, we create it now to point at your local revisions (optional). + + $ hg book feature-xyz + +Then, put it where it should be. + + $ hg pull -B @ + +Now @ will be placed to the same revision as the central repository. If some +changesets have been pulled, you may look at the previous topic to rebase your +work on top of it.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.rc.md Tue Feb 26 09:16:42 2019 +0100 @@ -0,0 +1,25 @@ +vanilla init scripts +==================== + +If a package provide a init script, it is installed as /etc/rc.d/name where +name is the canonical package name. + +Then enable it in /etc/rc.single or /etc/rc.multi. We recommend checking the +executable permissions to allow disabling/enabling services without editing +files. + +Example in /etc/rc.multi: + +```sh +if [ -x /etc/rc.d/acpid ]; then + /etc/rc.d/acpid start +fi +``` + +Don't forget to shutdown gracefully in /etc/rc.shutdown: + +```sh +if [ -x /etc/rc.d/acpid ]; then + /etc/rc.d/acpid stop +fi +```
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.templates.md Tue Feb 26 09:16:42 2019 +0100 @@ -0,0 +1,21 @@ +vanilla templates +================= + +The templates directory contains several files to help you creating new +packages. + +Build scripts +============= + +The following templates are available as build scripts. Just rename one of them +to the appropriate package name. + +- autotools.sh: for autoconf/automake programs, +- cmake.sh: for CMake programs, +- python.sh: for python (using setuptools) programs. + +Other files +=========== + +- template.info: the .info file required, +- rc: a sample init script file if applicable.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/STYLE.md Tue Feb 26 09:16:42 2019 +0100 @@ -0,0 +1,162 @@ +vanilla CODING STYLE +==================== + +File content +============ + +- Use UTF-8 charset, +- Use Unix line endings, +- Never write two blank consecutives blank lines. + +Indent +====== + +Use tabs to indent and spaces for alignment. Tabs are meant and designed for +indenting code and have the advantage of being configurable. On the other hand +to keep code clean, you must align content with spaces only *within* a line. + +Note: we recommend 8 columns to avoid high number of indentations. + +Shell +===== + +In shell programming try to stick with POSIX shell whenever possible. Otherwise, +set the shebang to a different shell. + +Style +----- + +- Try to keep lines shorter than 80 columns + +Functions +--------- + +Don't use `function` keyword, just keep the function name. + +```sh +usage() +{ +} +``` + +It's usually recommended to prefix functions names with the program name to +avoid collisions with global commands. + +```sh +foo_clean() +{ +} + +foo_process() +{ +} +``` + +Options +------- + +For options, use `getopts` and prefer short options to long unless necessary. +Also set OPTERR=0 to avoid printing errors and do it yourself for UX +consistency. + +```sh +OPTERR=0 +while getopts "v" arg; do + case $arg in + v) + verbose=1 + ;; + esac +done +``` + +Naming +------ + +Use `UPPERCASE` variables for global variables and `lowercase` for temporary or +local variables. + +Markdown +======== + +Headers +------- + +For 1st and 2nd level headers, use `===` and `---` delimiters and underline the +whole title. Otherwise use `###`. + +```markdown +Top level title +=============== + +Sub title +--------- + +### Header 3 + +#### Header 4 + +##### Header 5 + +###### Header 6 +``` + +Lists +----- + +Use hyphens for unordered lists for consistency, do not indent top level lists, +then indent by two spaces each level + +```markdown +- unordered list 1 +- unordered list 2 + - sub unordered item + +1. unordered list 1 +2. unordered list 2 + 2.1. sub unordered item +``` + +Code blocks +----------- + +You can use three backticks and the language specifier or just indent a block by +for leading spaces if you don't need syntax. + + ```cpp + std::cout << "hello world" << std::endl; + ``` + +And without syntax: + +```markdown + This is simple code block. +``` + +Tables +------ + +Tables are supported and formatted as following: + +```markdown +| header 1 | header 2 | +|----------|----------| +| item 1 | item 2 | +``` + +Alerts +------ + +It's possible to prefix a paragraph by one of the following topic, it renders a +different block depending on the output format: + +- Note: +- Warning: +- Danger: + +Then, if the paragraph is too long, indent the text correctly. + +```markdown +Note: this is an information block that is too long to fit between the limits so + it is split and indented. +```
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/templates/rc Tue Feb 26 09:16:42 2019 +0100 @@ -0,0 +1,68 @@ +#!/bin/sh +# +# Copyright (c) 2019 FirstName LastName <mailaddress> +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +# + +TEMPLATE_CMD=/usr/sbin/template +TEMPLATE_ARGS=--foo +TEMPLATE_PID=/var/run/template/template.pid + +template_start() +{ + echo "Starting template: $TEMPLATE_CMD $TEMPLATE_ARGS" + $TEMPLATE_CMD $TEMPLATE_ARGS -p $TEMPLATE_PID +} + +template_status() +{ + if [ -s $TEMPLATE_PID ]; then + echo "template is running with pid: `cat $TEMPLATE_PID`" + else + echo "template is not running" + fi +} + +template_stop() +{ + if [ -s $TEMPLATE_PID ]; then + echo "Stopping template..." + kill -QUIT $TEMPLATE_PID + fi +} + +template_restart() +{ + template_stop + sleep 3 + template_start +} + +case $1 in +start) + template_start + ;; +status) + template_status + ;; +stop) + template_stop + ;; +restart) + template_restart + ;; +*) + echo "usage: $(basename $0) restart|start|status|stop" + ;; +esac
--- a/templates/rc.template Sun Feb 24 16:36:07 2019 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,68 +0,0 @@ -#!/bin/sh -# -# Copyright (c) 2019 FirstName LastName <mailaddress> -# -# Permission to use, copy, modify, and/or distribute this software for any -# purpose with or without fee is hereby granted, provided that the above -# copyright notice and this permission notice appear in all copies. -# -# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -# - -TEMPLATE_CMD=/usr/sbin/template -TEMPLATE_ARGS=--foo -TEMPLATE_PID=/var/run/template/template.pid - -template_start() -{ - echo "Starting template: $TEMPLATE_CMD $TEMPLATE_ARGS" - $TEMPLATE_CMD $TEMPLATE_ARGS -p $TEMPLATE_PID -} - -template_status() -{ - if [ -s $TEMPLATE_PID ]; then - echo "template is running with pid: `cat $TEMPLATE_PID`" - else - echo "template is not running" - fi -} - -template_stop() -{ - if [ -s $TEMPLATE_PID ]; then - echo "Stopping template..." - kill -QUIT $TEMPLATE_PID - fi -} - -template_restart() -{ - template_stop - sleep 3 - template_start -} - -case $1 in -start) - template_start - ;; -status) - template_status - ;; -stop) - template_stop - ;; -restart) - template_restart - ;; -*) - echo "usage: $(basename $0) restart|start|status|stop" - ;; -esac