corrade-nucleus-nucleons – Blame information for rev 24

Subversion Repositories:
Rev:
Rev Author Line No. Line
20 office 1 # Contributing
2  
3  
4 ## Report Issues and Request Changes
5 If you find a bug, please report it, including environment and examples of current behavior and what you believe to be the correct behavior. The clearer your description and information, the more likely it is someone will be able to make progress on it. The default issue template will help guide you through this.
6  
7 ## How to Make Changes (Implement Fixes and New Features)
8 Fixes and enhancements are totally welcome. We prefer if you file an issue before filing a PR, as this gives us chance to discuss design details, but fee free to dive right in.
9  
10 ### 1. Build and Test Locally
11 While developing, you may build and test locally in JavaScript or Python implementation. The HTML beautifier is only implemented in JavaScript.
12  
13 * Familiarize yourself with the folder structure and code style before you dive in.
14 * Make changes to the implemnation of your choice
15 * Add tests to `/test/data/*/test.js`.
16 * Run `./build jstest` or `./build pytest` to run style checks, and to generate and run tests.
17 * Include all changed files in your commit - The generated test files are checked in along with changes to the test data files.
18  
19 ### 2. Ensure Feature Parity
20 You must port changes to the other implementation. **This is required**. Every time we make an exception to this requirement the project becomes harder to maintain. If you find yourself making changes and find you cannot port them to the other implementation due to implmentations being out of sync, you will begin to understand why this is required. We made this a requirement several years ago and there are still a open issues for changes that people at the time promised to port "in the next week or two". The entire HTML beautifier is an example of this. :(
21  
22 The implementations are already very similar and neither Python nor JavaScript are that hard to understand. Take the plunge, it is easier than you think. If you get stuck, move on to filing a Pull Request and we can discuss how to move forward.
23  
24 * Run `./build` (with no parameters) to run style checks, and to generate and run tests on both implementations.
25 * Include all changed files in your commit - The generated test files are checked in along with changes to the test data files.
26  
27 ### 3. Update Documentation and Tools
28 Update documentation as needed. This such as the README.md, internal command-line help, and file comments.
29 Also, check your change needs any tooling updates. For example, the CDN urls required added scripting to update automatically for new releases.
30  
31 ### 4. Submit a Pull Request
32  
33 * Run `./build full` locally after commit but before creation of Pull Request. You may start a Pull Request if this does not succeed, but the PR will not be accepted without additional changes.
34 * Include description of changes. Include examples of input and expected output if possible.
35 * Pull requests must pass build checks on all platforms before being accepted. We use travis-ci and appveyor to run tests on Linux and Windows, across multiple versions of Node.js and Python.
36  
37 # Folders
38  
39 ## Root
40 Some files related to specific implementations or platforms are found in the root folder, but most are cross-project tools and configuration.
41  
42 ## js
43 Files related to the JavaScript implmentations of the beautifiers.
44  
45 ## python
46 Files related to the Python implmentations of the beautifiers.
47  
48  
49 ## web
50 Files related to http://jsbeautifier.org/.
51  
52 ## test
53 Test data files and support files used to generate implmentation-specific test files from them.
54  
55  
56 # Branches
57 We use the `master` branch as the primrary development branch.
58  
59 ## Releases
60 Each platform has a branch that tracks to the latest release of that platform.
61  
62 * `python-stable`
63 * `node-stable`
64 * `gh-pages`
65  
66 ## Functional Parity
67 Keeping the platforms in some semblance of functional parity is one of the key features of this project. As such, there branches for the last time synchronization occured and when it stablized.
68  
69 * `sync`
70 * `sync-stable`
71  
72 ## Attic
73 This project has been around for a while. While some parts have improved significantly over time, others fell
74 into disrepair and were mothballed.
75  
76 ### PHP
77 There is an out-of-date version of the beautifier available on branch `attic-php`. If you're interested
78 in using it feel free. If you plan to enhance it, please consider joining this project, and updating this
79 version to match current functionality.
80  
81 ### Other Languages
82 Versions of the beautifier adapted to other languages are at least two years out-of-date and are
83 available on branch `attic-other`. Take a look and feel free to resurrect them, but know it's pretty
84 dusty back there.
85  
86 ### Generic Eval Unpacker
87 The `attic-genericeval` branch includes an unpacker that call `eval` on whatever source is passed to it.
88 Useful when working with source that unpacks itself when eval is called on it, but also unsafe. We keep
89 it on this separate branch to keep it from hurting the other children.
90  
91 # Publishing a Release
92 Each platform has it's own release process.
93  
94 NOTE: Before you do any of these make sure the latest changes have passed the travis-ci build!
95  
96 ##Web
97 Merge changes from `master` to `gh-pages` branch. This is very low cost and can be done whenever is convenient.
98  
99 ##Python
100 NOTE: For now, we'd like to keep python and node version numbers synchronized,
101 so if you publish a python release, you should publish a node release as well.
102  
103 To perform these steps you will need:
104 1. A pypi user account from https://pypi.python.org/pypi?%3Aaction=register_form .
105 2. Permissions to the jsbeautifier package. File an issue here on github and the appropriate person will help you.
106  
107 We basically follow the simplest release path found at http://docs.python.org/2/distutils/packageindex.html . :
108  
109 ```bash
110 git clean -xfd
111 # replace 0.0.1 with the actual version number you want to use
112 NEW_VERSION=0.0.1
113 echo "__version__ = '$NEW_VERSION'" > python/jsbeautifier/__version__.py
114 git commit -am "Python $NEW_VERSION"
115 cd python
116 python setup.py register
117 python setup.py sdist bdist_wininst upload
118 git push
119 ```
120  
121 ##Node
122 NOTE: For now, we'd like to keep python and node version numbers synchronized,
123 so if you plan to publish a node release, you should publish a python release *first*,
124 then perform the steps below.
125  
126 To perform these steps you will need:
127 1. An npmjs.org user account from https://npmjs.org/signup .
128 2. Permissions to the js-beautify module on npmjs.org. File an issue here on github and the appropriate person will help you.
129  
130 Npm makes this process even simpler than python's and creates a tag for the release as well.
131  
132 ```bash
133 git clean -xfd
134 # replace 0.0.1 with the actual version number you want to use
135 NEW_VERSION=0.0.1
136 npm version $NEW_VERSION
137 npm publish .
138 git push --tags
139 ```