Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 112 lines (68 sloc) 4.848 kB
b44768c @yrashk Added initial CONTRIBUTING.md
yrashk authored
1 CONTRIBUTING
2 ============
3
4 How can I suggest a new package?
5 --------------------------------
6
7 Just [open an issue](https://github.com/agner/agner/issues) with your suggestion.
8
9 How can I create a new package?
10 -------------------------------
11
12 You can create a spec repository by forking and renaming [template package repo](https://github.com/agner/agner.template)
218e50a @yrashk Added reference to 'agner create' command in CONTRIBUTING.md
yrashk authored
13 and later on submitting it for inclusion by [opening an issue](https://github.com/agner/agner/issues). One of the most
14 convenient ways to do this is to use `agner create` command. Please note
15 that if you don't have owner permissions at `agner` GitHub account,
16 please supply your account name using `--github-account NAME` option.
17 The last step (opening an issue to include it into the central repository) is only necessary if you want this package to be published on a "central" index.
b44768c @yrashk Added initial CONTRIBUTING.md
yrashk authored
18 If you want to keep it semi-private, you can just use it from your own index.
19
5010b7a @yrashk Added a little bit more information on tag shuffling to CONTRIBUTING.md
yrashk authored
20 Mastering specification
21 -----------------------
22
b2fcaa4 @yrashk Fixed broken link in README.md
yrashk authored
23 First of all, please take some time to read through [README](README.md) to make sure you understand all the concepts,
5010b7a @yrashk Added a little bit more information on tag shuffling to CONTRIBUTING.md
yrashk authored
24 especially how versioning is done.
25
26 Also, even though in Git world you can be crucified for deleting remote tags (`release` versions in our lingo), in Agner,
27 even not encouraged, this type of action is tolerable if you need to change the specification of an already published release.
28 `.agner` repos are intended for quick fresh cloning so shuffling tags in them is not that critical. If you do anticiapte anticipate that somebody has a fork of your `.agner` repo, though, please communicate your tag changes to them, just in case. One of
29 the ways might be adding some README or NOTES file into your `.agner` repo.
30
b44768c @yrashk Added initial CONTRIBUTING.md
yrashk authored
31 Before commiting your agner.config, please make sure you ran `agner verify` on it so it passes at least
5010b7a @yrashk Added a little bit more information on tag shuffling to CONTRIBUTING.md
yrashk authored
32 some validity checks.
33
90339e4 @yrashk Fixing markdown syntax in CONTRIBUTING.md
yrashk authored
34 ### Build command
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
35
36 If your target repository can't be built by simply invoking `rebar get-deps && rebar compile` then you need to supply
37 a `build_command` property, for example:
38
39 {build_command, "make"}.
40
c16fa32 @yrashk build_command and rebar_compatible are no longer exclusive, build_com…
yrashk authored
41 Alternatively, you can also use it to finalize build process after rebar get-deps & compile for rebar compatible projects.
42
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
43 The build command will be invoked in checked out directory containing target repository.
44
90339e4 @yrashk Fixing markdown syntax in CONTRIBUTING.md
yrashk authored
45 ### Install command
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
46
47 If your target repository can't be built by simply invoking `rebar get-deps && rebar compile` then you need to supply
48 a `install_command` property, for example:
49
50
51 {install_command, "make install"}.
52
53 The install command will be invoked in checked out directory containing target repository.
54
55
90339e4 @yrashk Fixing markdown syntax in CONTRIBUTING.md
yrashk authored
56 ### Environment Variables
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
57
58 Here's the current list of environmentvariables that will be available to build & install commands:
59
c4926b2 @yrashk Fixed a wrong word in CONTRIBUTING.md
yrashk authored
60 * AGNER -- Absolute path to the agner script file
7b2433c @yrashk Now every installed package is isolated in its own directory and can …
yrashk authored
61 * AGNER_PREFIX -- Root agner's directory (defaults to `/usr/local/agner`)
ed2e895 @yrashk Added minimal documentation on AGNER_PACKAGE_REPO variable
yrashk authored
62 * AGNER_PACKAGE_REPO -- Path to checked out .agner repo
85fe0c8 @yrashk Add AGNER_PACKAGE_NAME and AGNER_PACKAGE_VERSION environment variable…
yrashk authored
63 * AGNER_PACKAGE_NAME -- Name of the package
64 * AGNER_PACKAGE_VERSION -- Version of the package
7b2433c @yrashk Now every installed package is isolated in its own directory and can …
yrashk authored
65 * AGNER_INSTALL_PREFIX -- A place where install procedure should consider putting installable files to. Right now it equates to
66 `AGNER_PREFIX/agner/packages/<package_name>-<package_version>`
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
67
68 More variables to come later.
1b43447 @yrashk Added documentation on hidden branches & tags in CONTRIBUTING.md
yrashk authored
69
b84bf97 @yrashk Very minor fix in CONTRIBUTING.md
yrashk authored
70 ### Private Branches & Tags
1b43447 @yrashk Added documentation on hidden branches & tags in CONTRIBUTING.md
yrashk authored
71
72 If you want to have either branches or tags that shouldn't be exposed to the end user as versions when they inquire using
73 `agner versions`, simply prepend your branch or tag name with `%` (comment) symbol and it will be hidden from the general public.
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
74 It will still be possible to use such versions explicitly, though (for example, `agner spec erlv8 -v @%test` for a branch called `%test`)
75
76 ## Tips & Tricks
77
78 ### Rewriting multiple versions
79
80 Ever found yourself in a situation when you made a typo across multiple versions of the specification? I know I did, multiple
81 times. So here's a quick-n-dirty solution for this.
82
83 Let's assume you have a branch named `release` (@release flavour) and some release versions that you want to rewrite; and you need to change misspelled `nae` property to `name`.
84
85 What you can do is:
86
87 1. Create new `release2` branch
88
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
89 git checkout -b release2
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
90
91 2. Do the actual replacement
92
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
93 git tag -l | sort | xargs -I {} sh -c 'git cherry-pick -n {} && cat agner.config | sed s/nae/name/g > agner.new && mv agner.new agner.config && git add agner.config && git commit -C {} && git tag -d {} && git tag {}'
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
94
95 3. Remove remote `release branch`
96
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
97 git push origin :release
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
98
99 4. Push `remote2` as `remote`
100
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
101 git push origin release2:release
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
102
103 5. Remove remote tags:
104
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
105 git tag -l | xargs -I {} git push origin :{}
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
106
107 6. Push tags:
108
3b7fb9d @yrashk Added a little note to CONTRIBUTING.md section on how to rewrite mult…
yrashk authored
109 git push origin --tags
110
218e50a @yrashk Added reference to 'agner create' command in CONTRIBUTING.md
yrashk authored
111 P.S. If you want to stick to proper release version tags only (for example, if you use hidden % tags), you might want to use `agner versions PACKAGE --no-flavours` command instead of `git tag -l`
Something went wrong with that request. Please try again.